Erros e limites

Formato do erro

Toda resposta de erro da API REST tem o mesmo corpo JSON:

{
  "code": "rate_limited",
  "message": "Too many requests for this endpoint group. Retry after the current minute.",
  "retry_after": 42
}

Campo	Sempre presente	Significado
code	sim	Código estável, para o seu código tratar.
message	sim	Explicação para pessoas, em inglês. Pode mudar; não compare texto.
retry_after	não	Segundos até poder tentar de novo (rate_limited).
limit	não	Limite que foi atingido (quota_exceeded).
remaining	não	Quanto ainda resta na janela atual (quota_exceeded).

Códigos

HTTP	code	Quando acontece
400	invalid_request	Parâmetro ou corpo inválido, parâmetro desconhecido, repetido ou faltando.
400	period_too_long	O intervalo de datas passa de 90 dias.
400	invalid_cursor	O cursor expirou, foi alterado ou a consulta mudou entre as páginas.
400	idempotency_key_required	Uma escrita chegou sem o cabeçalho Idempotency-Key.
400	invalid_roas_target	ROAS alvo fora do intervalo de 1,0 a 35,0.
400	invalid_status_transition	Tentativa de reativar uma campanha encerrada.
401	invalid_api_key	Chave ausente, mal formada, desconhecida, revogada ou expirada.
403	not_contracted	A conta não tem o add-on Open API ativo.
404	not_found	A rota não existe, ou o recurso não existe ou não é da sua conta. Os dois casos têm a mesma resposta.
409	idempotency_conflict	A mesma Idempotency-Key foi reusada com outro corpo.
409	opportunity_not_applicable	A oportunidade já foi aplicada, descartada ou expirou.
409	opportunity_locked	A mesma oportunidade, ou a mesma requisição, ainda está em execução.
429	rate_limited	O limite por minuto do grupo de rotas acabou.
429	quota_exceeded	A cota mensal da conta acabou.
500	internal_error	Erro inesperado na GoBots.
501	not_implemented	O recurso ainda não existe para esse marketplace (hoje o Ads cobre só o Mercado Livre, meli).
502	source_rejected	O marketplace recusou a escrita.
503	source_unavailable	A origem dos dados está indisponível. Tente de novo mais tarde.

Outras respostas que você pode receber:

• 202 em uma escrita: a mudança ainda está em andamento no marketplace. Consulte a URL do cabeçalho Location até ela terminar.
• 304 em uma leitura com If-None-Match: nada mudou desde o ETag enviado. Ainda conta como uma requisição.

Limites por plano

Plano	metrics (req/min)	ads (req/min)	meta (req/min)	Cota mensal
starter	60	60	600	20.000
pro	300	300	600	200.000
enterprise	1.000	1.000	1.000	2.000.000

• Os limites valem por conta, não por chave: todas as chaves e assistentes conectados dividem o mesmo orçamento.
• O limite por minuto é uma janela fixa de 60 segundos para cada grupo de rotas.
• A cota mensal vale para os grupos metrics e ads e reinicia no dia 1 de cada mês, às 00:00 UTC.
• Uma requisição recusada pelo limite por minuto não consome cota.
• GET /v1/me mostra o plano, os limites e o consumo do mês.

Grupos de rotas

Grupo	Rotas	Ferramentas MCP	Conta na cota mensal
metrics	/v1/metrics, /v1/metrics/dictionary	describe_metrics, get_metrics	sim
ads	/v1/ads/** (leituras e escritas)	as demais ferramentas	sim
meta	/v1/me, /v1/stores, /v1/ads/{marketplace}/actions/**	list_stores	não, na API REST

No servidor MCP, toda chamada de ferramenta consome uma unidade da cota mensal, inclusive list_stores, e uma escrita confirmada consome duas. A API REST e o MCP dividem a mesma cota.

Cabeçalhos de limite

As respostas trazem o limite e o que resta dele:

RateLimit-Policy: "ads";q=300;w=60, "quota";q=200000;w=2592000
RateLimit: "ads";r=287;t=42

• RateLimit-Policy: q é o limite e w a janela em segundos. A parte quota só aparece nos grupos que contam na cota mensal.
• RateLimit: r é quanto resta e t quantos segundos faltam para a janela reiniciar.
• Retry-After: só nas respostas 429, em segundos.

Respostas 401 e 403 não trazem esses cabeçalhos.

O que fazer ao receber 429

1. Leia o cabeçalho Retry-After e espere esse número de segundos.
2. Tente de novo. Em rate_limited a espera é até o próximo minuto; em quota_exceeded, até o próximo mês.
3. Se você bate no limite com frequência, distribua as chamadas no tempo ou fale com o seu consultor sobre um plano maior.

Outros limites

Limite	Valor
Tamanho da página (limit)	1 a 500, padrão 50. A próxima página vem em meta.next_cursor; null indica o fim.
Validade do cursor	1 hora
Intervalo de datas	Até 90 dias. As métricas de Ads aceitam datas de até 90 dias atrás.
Linhas de métricas	Até 10.000 por resposta (períodos × escopos × lojas).
Filtro de lojas	Até 50 ids.
Escritas em lote (REST)	Até 50 ids por chamada.
apply_opportunities (MCP)	Até 20 oportunidades por chamada.
Chaves ativas por conta	10

Idempotência nas escritas

Toda escrita da API REST exige o cabeçalho Idempotency-Key com um UUID:

curl -X PATCH https://open-api.live.gobots.com.br/v1/ads/meli/campaigns/123 \
  -H "Authorization: Bearer $GOBOTS_API_KEY" \
  -H "Idempotency-Key: 0b6f2a8e-1c1d-4f5e-9d1a-6a1f7f3d2c4b" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

• A GoBots guarda cada chave por 24 horas.
• Repetir a mesma chave com o mesmo corpo devolve a resposta original, com o cabeçalho Idempotent-Replayed: true. Nada é executado de novo.
• Repetir a mesma chave com outro corpo responde 409 idempotency_conflict.
• Use uma chave nova para cada mudança e a mesma chave ao tentar de novo a mesma mudança.