# 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: ```json {"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 `#` (por exemplo, [`#account_not_found`](#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`](#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`](#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: | Nível | Ritmo sustentado | Rajada | |---|---|---| | Global do mcplace | cerca de 4 chamadas/s | 8 | | Sua conta (fair-use) | 4 chamadas/s | 15 | | Envio de mensagens | 8 por minuto | — | | Leitura de mensagens, busca de reclamações, métricas de Ads, visitas | 60 por minuto cada | — | | Mensagens, todo o mcplace (envio e leitura, cada) | 400 por minuto | — | | Consulta de estoque, todo o mcplace | 80 por minuto | — | Todos chegam com o código [`rate_limited`](#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. | Mensagem | O que fazer | |---|---| | `O mcplace está recebendo muitas chamadas ao Mercado Livre neste instante. Tente novamente em N s.` | Esperar `retry_after_s` segundos. | | `Limite de velocidade de sua conta atingido (fair-use). Reduza a frequência de chamadas e tente novamente em N s.` | O agente está disparando chamadas demais em paralelo. Prefira uma tool de agregação a várias leituras. | | `Limite interno do mcplace para envio de mensagens atingido (N/min por conta). Aguarde um minuto. Tente novamente em N s.` | Esperar um minuto. O limite é do mcplace, não do Mercado Livre. | | `O Mercado Livre limitou temporariamente as chamadas (429). Tente novamente em alguns instantes.` | O servidor já tentou 3 vezes. Depois de 5 respostas assim em 1 minuto, aquele tipo de chamada fica pausado por 30 segundos. | 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. | Tool | Teto | Aviso na resposta | |---|---|---| | `aggregate_orders`, `rank_items` | 2000 pedidos | `_truncated: true` e `_meta.truncated: true` | | `rank_items` por `visits`, `conversion` ou `revenue_per_visit` | 50 anúncios | `_meta.truncated: true` | | `claims_open_summary` | 500 reclamações | `_meta.truncated: true` | | `ml_ads_performance` | o `limit` enviado (máx. 100) | `_meta.truncated: true` quando o Mercado Livre tinha mais linhas | | `query` | 20 requisições ao Mercado Livre ou 5000 linhas | `_meta.truncated: true` | 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](/seguranca). ## Credencial e endereço ### unauthenticated ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text Esta conta foi desconectada no painel. ``` A conta foi desconectada no painel. Conecte de novo para voltar a usar. Campos: `account`. ### reauthorize_required ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text Este marketplace não oferece esta operação. ``` Este marketplace não oferece a operação pedida. Campos: `marketplace`, `tool`. ### marketplace_unavailable ```text O adaptador de {marketplace} ainda não está disponível. ``` O marketplace ainda não tem conector no mcplace. Campos: `marketplace`. ### upstream_error ```text 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`. | Frase comum (`status`) | Causa comum | |---|---| | `O Mercado Livre rejeitou a requisição (400).` | Parâmetro que o Mercado Livre não aceita para aquele anúncio ou pedido. | | `Sem permissão no Mercado Livre para esta ação (403).` | A conta não tem aquele recurso, ou o usuário não é o administrador. | | `Recurso não encontrado no Mercado Livre (404).` | Id errado, ou de outra conta. | | `Conflito de versão no Mercado Livre (409).` | Outra alteração chegou ao mesmo tempo. Repita. | Um token do Mercado Livre inválido (401) chega como [`reauthorize_required`](#reauthorize_required). ## Limites ### rate_limited ```text 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](#rate-limits). Campos: `retry_after_s`, `scope`, `lane`, `cap`. ### quota_exceeded ```text 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](#free-quota). 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 ```text 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 ```text 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 ```text 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 ```text Falha interna. Tente novamente em alguns instantes. ``` Falha nossa. Tente de novo em instantes e, se persistir, abra um chamado com o `request_id`.