Erros e limites

O que o seu agente recebe quando algo não passa, e o que fazer em cada caso.

Como um erro chega ao agente

Todo erro é um resultado de tool marcado como erro. Ele traz a frase em português na primeira linha e, logo depois, um objeto error com o código em que o agente se apoia:

{"error": {"code": "account_not_found", "message": "Conta não encontrada para este agente.", "request_id": "d79d65f1a74b7127", "billable_calls": 0, "upstream_calls": 0, "given": "nao-existe"}}

• code é estável: o agente decide pelo código, nunca pela frase. Cada código tem uma seção nesta página, no endereço #<código> (por exemplo, #account_not_found).
• message é a frase para repassar a você como veio, sem parafrasear.
• request_id identifica a chamada. Informe-o num chamado de suporte.
• billable_calls diz se a chamada contou na cota (1) ou não (0), e upstream_calls quantas requisições chegaram ao marketplace.
• Os demais campos dependem do código e estão listados em cada seção.

Erros do Mercado Livre chegam com o código upstream_error, sem o prefixo em inglês do protocolo. Argumento fora do formato (um limit acima do máximo, texto longo demais) é barrado antes, pela validação do protocolo, e essa mensagem vem em inglês, sem código.

Respostas com sucesso trazem um objeto _meta com request_id, billable_calls, upstream_calls, partial e truncated.

Cota do plano Grátis

• 50 chamadas por dia, durante 7 dias a partir da primeira chamada de tool. Planos pagos não têm cota.
• Os 7 dias não reiniciam. Quando acabam, as tools cobradas passam a responder free_period_ended até a assinatura de um plano.
• O dia vira à 00:00 UTC, 21:00 no horário de Brasília.
• A chamada é contada antes de rodar. Se o Mercado Livre responder com erro depois, ela já foi consumida. Exceção: uma query malformada é recusada antes de contar.
• Uma escrita barrada também conta: a cota é verificada antes da permissão. A exceção é uma recusa que vem antes da cota: tool bloqueada na conta, conta só leitura, escritas pausadas ou sem permissão no vínculo — essa não conta.
• A cota debitada é sempre a do dono da conta, não a de quem perguntou.
• Uma leitura recusada por cota não vira linha de auditoria — ela aparece só no Uso.
• Não contam: connection_status, whoami, describe_query_schema, ml_sites, ml_shipment_statuses, ml_claim_reasons, ml_app_limits, open_support_ticket e suggest_improvement.

Ao estourar, o código é quota_exceeded. O consumo do dia aparece em Uso no painel.

Limite de velocidade

O Mercado Livre impõe um teto por aplicativo, dividido entre todas as contas do mcplace. Por isso existem três níveis, em todos os planos:

Todos chegam com o código rate_limited; o campo scope diz qual nível foi atingido.

Uma varredura de uma única conta interrompida por esses limites devolve o que já leu, com _meta.truncated: true e _meta.retry_after_s. Se o limite vier antes da primeira linha, a tool falha com rate_limited e retry_after_s. Em consulta de várias contas, _meta.retry_after_s é o maior valor entre as contas recusadas.

A regra para o agente: se vier retry_after_s, esperar esse tempo; se não, esperar alguns segundos, tentar de novo uma vez e, se persistir, avisar você.

Resultado parcial

Algumas tools param de varrer ao chegar num teto.

Número parcial apresentado como exato é o pior erro possível aqui. Inclua no pedido: “diga se o resultado veio parcial”.

Janelas de data

• Datas sempre em AAAA-MM-DD. Não existe “ontem” nem “mês passado”: quem calcula é o agente.
• Ads: só os últimos 90 dias, e date_to não pode estar no futuro. O dia corrente é atualizado às 10:00 (horário de Brasília).
• Visitas: janela máxima de 150 dias, com date_from e date_to obrigatórios.
• query em pedidos e reclamações: exige filtro de data ou de id. Varredura sem limite é recusada.

Atualização dos dados

Leituras ficam em cache por até 60 segundos por conector. Uma escrita feita pelo seu agente limpa o cache daquele conector na hora, então ele sempre lê o que acabou de gravar.

Catálogo de códigos

Cada código abaixo traz a frase exata (com {campo} onde entra um valor), o que fazer e os campos que acompanham o erro. Escritas barradas e as regras do servidor estão explicadas em Segurança e controle.

Credencial e endereço

unauthenticated

Chamada não autenticada.

A conexão chegou sem credencial válida. Confira a URL do painel ou a chave de API configurada no cliente.

principal_invalid

Token sem identificação de conta (org_id ausente).

O token não identifica uma conta. Gere a credencial de novo no painel.

credential_expired

Esta chave expirou. Gere outra no painel.

A chave de API passou da validade. Crie outra em API keys. Campos: expired_at.

narrowing_not_applicable

Este caminho só vale em espaço de organização.
Este caminho vale só em organização do tipo Partner.

A URL usa um trecho (/c/…) que não vale para este espaço de trabalho. Use a URL do painel sem esse trecho. A segunda frase é a variante do mesmo código para outro caso. Campos: segment, workspace_kind.

url_credential_not_narrowed

Esta credencial precisa ser usada como URL. Cole a URL inteira no cliente, em vez de mandar o token no cabeçalho `Authorization`.

A URL do painel foi enviada como cabeçalho. Cole a URL inteira no campo de endereço; para cabeçalho, use uma chave de API.

unknown_toolset

Toolset desconhecido.

O trecho /t/… da URL não existe. Remova-o ou use um dos que a mensagem lista em toolsets. Campos: toolsets.

Qual conta

account_required

Diga a conta: toda escrita precisa de uma conta explícita.

Toda escrita precisa dizer a conta. Repita com account (o apelido, por exemplo); veja connection_status. Campos: kind.

account_not_found

Conta não encontrada para este agente.

Nenhuma conta alcançável atende pelo que foi enviado em given. Chame connection_status e use um dos endereços que ele devolve. Campos: given.

account_out_of_scope

Esta chave só alcança a conta {account}. Informe essa conta ou use uma chave sem restrição de conta.
Esta credencial só alcança a conta «{account}». Use outra chave para agir em outra conta.

A credencial está restrita a uma conta (account). Use essa conta ou outra credencial. A segunda frase é a variante do mesmo código para outro caso. Campos: account, given.

account_ambiguous

Mais de uma conta atende por «{given}». Diga qual.
Mais de uma conta pode responder. Diga qual.

Mais de uma conta serve. A mensagem traz candidates: escolha uma e repita com account. A segunda frase é a variante do mesmo código para outro caso. Campos: given, candidates, candidates_truncated.

no_accounts

Nenhuma conta conectada. Conecte uma conta no painel.

O espaço de trabalho não tem conta conectada. Conecte uma no painel.

Estado da conta

account_suspended

Este conector está suspenso (limite do plano ou pagamento pendente). Reative fazendo upgrade no painel.
Esta conta está suspensa no mcplace. O titular precisa reativá-la.

O conector foi suspenso (limite do plano ou pagamento pendente). Reative no painel. Em espaço de organização chega a segunda frase, que não expõe o plano do cliente. Campos: account.

account_disconnected

Esta conta foi desconectada no painel.

A conta foi desconectada no painel. Conecte de novo para voltar a usar. Campos: account.

reauthorize_required

Esta conta precisa de reautorização no marketplace. Reautorize no painel.

A autorização no marketplace caiu ou expirou. Reautorize a conta no painel. Campos: account, marketplace.

subscription_canceled

Assinatura cancelada. Reative no painel para continuar.
Esta conta não está ativa no mcplace. Fale com o cliente.

A assinatura foi cancelada. Reative em Assinatura no painel. Em espaço de organização chega a segunda frase, que não expõe o plano do cliente.

Escrita barrada

read_only

Este conector está em modo somente-leitura. Desative o modo no painel para permitir escritas.

O conector está em somente leitura. Quem pode mudar aparece em who_can_change. Campos: account, who_can_change.

missing_scope

Este token não tem escopo de escrita (write).

A credencial não tem permissão de escrita (por exemplo, uma chave de API criada como somente leitura). Campos: required_scope.

confirmation_missing

Esta ação exige confirmação explícita. Repita a chamada com confirm=true após confirmar com o usuário.

A ação exige confirmação. Pergunte ao usuário e repita a mesma chamada com confirm=true. Campos: tool.

writes_paused

As escritas desta conta estão pausadas.

As escritas desta conta estão pausadas no painel. Quem pode mudar aparece em who_can_change. Campos: account, who_can_change.

tool_blocked_on_account

A tool {tool} está bloqueada nesta conta. O dono da conta libera no painel, em Conectores.

A tool está bloqueada nesta conta. O dono libera em Conectores. Campos: tool, account.

tool_not_allowed

Esta ferramenta não está liberada nesta conexão.

A tool não está liberada nesta conexão (por exemplo, uma escrita numa URL com /t/leitura). Campos: tool.

tool_rules_unavailable

Não consegui ler as regras de tools desta conta agora. Tente de novo em instantes.

Falha passageira ao ler as regras da conta. Tente de novo em instantes.

guard_rejected

Variação de preço acima do limite de segurança (±{limit_pct}). A alteração não foi enviada.
Estoque não pode ser negativo. A alteração não foi enviada.

Uma regra de segurança do servidor recusou a alteração antes de enviá-la. Nada mudou no marketplace. A segunda frase é a variante do mesmo código para outro caso. Campos: guard, limit, given, current.

not_actionable

Esta conversa está bloqueada/fechada pelo Mercado Livre. Só é possível responder conversas ativas iniciadas pelo comprador.

O Mercado Livre não permite agir sobre este objeto no estado atual. A mensagem traz state e allowed. Campos: object, state, allowed.

Organizações

grant_read_only

O cliente liberou só leitura nesta conta.

Só em espaço de organização: o cliente liberou só leitura nesta conta. Campos: account, who_can_change.

grant_revoked

O vínculo com este cliente foi revogado.

Só em espaço de organização: o vínculo com o cliente foi revogado. Campos: account.

role_forbidden

Seu papel na organização não permite esta ação.

Só em espaço de organização: o papel da pessoa não permite a ação. O motivo exato não é informado ao agente. Campos: account, tool.

cross_tenant_aggregate_forbidden

Não é possível somar ou comparar contas de clientes diferentes.

Só em espaço de organização: somar ou comparar contas de clientes diferentes é recusado. A mensagem traz retry_with, a chamada corrigida. Campos: clients, params, retry_with.

not_supported_in_workspace

Abra o chamado pelo painel: chamados por agente ainda não valem em espaço de organização.

Só em espaço de organização: abra o chamado pelo painel. Campos: workspace_kind.

Consultas a várias contas

fanout_budget_exceeded

Mais contas do que o limite por chamada. Use o cursor para continuar.

A consulta passou do número de contas por chamada. Continue com o cursor devolvido. Campos: max_accounts, cursor, remaining.

fanout_deadline_exceeded

A busca passou do tempo limite desta chamada. Use o cursor para continuar de onde parou.

A consulta passou do tempo limite. Continue com o cursor devolvido. Campos: timeout_s, cursor, remaining.

Marketplace

not_supported_on

Este marketplace não oferece esta operação.

Este marketplace não oferece a operação pedida. Campos: marketplace, tool.

marketplace_unavailable

O adaptador de {marketplace} ainda não está disponível.

O marketplace ainda não tem conector no mcplace. Campos: marketplace.

upstream_error

Erro do Mercado Livre.

O Mercado Livre recusou ou falhou. status traz o código HTTP; num erro 4xx a frase traz o detalhe original, que diz o que corrigir. Num 5xx, tente de novo mais tarde. Campos: marketplace, status, upstream_code.

Um token do Mercado Livre inválido (401) chega como reauthorize_required.

Limites

rate_limited

O Mercado Livre limitou temporariamente as chamadas (429). Tente novamente em alguns instantes.

Um limite de velocidade foi atingido. scope diz qual e retry_after_s, quando houver, quanto esperar. As frases de cada limite estão em Limite de velocidade. Campos: retry_after_s, scope, lane, cap.

quota_exceeded

Limite diário do plano Grátis atingido ({calls_per_day} chamadas/dia). Ferramentas de schema/status continuam livres. Faça upgrade no painel para chamadas ilimitadas.
Esta conta atingiu o limite diário de chamadas. O contador zera em {resets_at}.

A cota diária do plano Grátis acabou. Veja Cota do plano Grátis. Em espaço de organização chega a segunda frase, que não expõe o plano do cliente. Campos: calls_per_day, used, resets_at, source, account, upgrade_url.

Instrução ao agente:

1. Pare de chamar tools cobradas nesta conversa. Não tente de novo e não troque de tool para contornar a recusa.
2. Responda com o que já buscou e diga que o resultado é parcial.
3. Diga em uma frase que o limite de hoje foi atingido e quando o contador zera, em horário local, a partir de resets_at.
4. Ofereça o upgrade_url. connection_status e as tools de schema continuam funcionando.

free_period_ended

O período grátis de 7 dias desta conta terminou em {free_ended_at}. Ferramentas de schema/status continuam livres. Assine um plano em {upgrade_url} para continuar usando as ferramentas.
Esta conta não pode usar as ferramentas no momento. Fale com o cliente.

O período grátis de 7 dias da conta terminou. Ele começa na primeira chamada de tool e não renova: só uma assinatura libera as ferramentas de novo. A chamada recusada não conta na cota do dia. connection_status e as ferramentas de schema continuam funcionando. Em espaço de organização chega a segunda frase, que não expõe o plano do cliente. Campos: free_ended_at, upgrade_url, account.

Instrução ao agente:

1. Pare de chamar tools cobradas nesta conversa. Não tente de novo e não troque de tool para contornar a recusa.
2. Responda com o que já buscou e diga que o resultado é parcial.
3. Diga em uma frase que o período grátis acabou e não zera.
4. Ofereça o upgrade_url. connection_status e as tools de schema continuam funcionando.

support_rate_limited

Limite de {limit} chamados/sugestões por dia atingido. Use o painel (Ajuda) se for urgente.

Limite diário de chamados e sugestões pelo agente. Use Ajuda no painel. Campos: limit, resets_at.

Argumento e falha interna

invalid_argument

Informe pack_id ou order_id.
Informe `account`; `connector_id` está em depreciação.

Um argumento veio fora do formato. field diz qual; a frase diz o que falta. A segunda frase é a variante do mesmo código para outro caso. Campos: field, given.

internal_error

Falha interna. Tente novamente em alguns instantes.

Falha nossa. Tente de novo em instantes e, se persistir, abra um chamado com o request_id.