Erros, limites e boas práticas

Formato de erro

{
  "error": true,
  "code": "validation_failed",
  "user_message": "O nome da campanha é obrigatório",
  "request_id": "0b6f…",
  "errors": { "campaign_name": "O nome da campanha é obrigatório" }
}

user_message está sempre em português e pode ser mostrada ao usuário final. Detalhes internos (banco, Meta) nunca são devolvidos — ficam nos logs, ligados ao request_id/log_id.

HTTP	`code`	Significado
400	`invalid_request`, `invalid_json`, `selection_missing`	Corpo fora do formato (o campo vem em `user_message` e em `issues`)
401	`unauthorized`	Sem credencial, chave revogada/expirada ou token inválido
403	`insufficient_scope`	Falta permissão (veja `required_scope`)
403	`selection_denied`, `forbidden`	Cliente arquivado, conta de outra BM/desativada/inativa na Meta, recurso de outro usuário
404	`not_found`, `campaign_not_found`, `post_not_found`, `client_not_found`, `client_archived`	Recurso inexistente (ou cliente arquivado)
409	`execution_running`, `conflict`, `ambiguous_client`	Execução já em andamento / reexecução já feita / mais de um cliente com esse nome (use o id)
422	`validation_failed`	Regras de negócio — veja `errors` por campo
422	`audiences_unavailable`	Público personalizado que a conta não pode usar
429	`rate_limited`	Limite da API do Media Ops (veja `Retry-After`)
429	`meta_rate_limited`	A Meta limitou a conta (veja `retry_after_seconds`)
502	`upstream_error`, `meta_error`	Falha na Meta ou no Google Drive

Limites da API

Por chave de API (ou aplicativo OAuth), por minuto:

Classe	Limite	Exemplos
Leitura	300	`GET`, consultas
Escrita	60	`POST`/`PATCH`/`DELETE` comuns
Pesada	10	`POST /campaigns`, `/campaigns/validate`, `/audiences/engagement`, sincronizações

As respostas trazem x-ratelimit-limit e x-ratelimit-remaining. Ao receber 429, espere Retry-After segundos.

Limites da Meta

A Meta limita chamadas por conta de anúncio (código 17 e semelhantes). Durante uma criação, o servidor espera e reenvia sozinho — você verá progress.throttle.paused = true. Só depois de 30 minutos de espera o item é marcado como erro.

Para consultas diretas (/meta/*), um bloqueio vira 429 meta_rate_limited com retry_after_seconds.

Boas práticas

Valide com POST /campaigns/validate antes de criar.
Guarde o job_id. Em caso de queda da sua automação, retome consultando /executions/{job_id}/progress — a criação continua no servidor.
Não reenvie POST /campaigns para "tentar de novo": use POST /executions/{job_id}/retry, que reaproveita o que já foi criado.
Use chaves com o mínimo de permissões e com validade.
Envie x-request-id próprio se quiser correlacionar com seus logs; ele é devolvido na resposta.