Erros

Os erros compartilham um único envelope (veja a visão geral). Use code nas ramificações do seu código, registre meta.request_id nos logs e trate message como um texto em inglês para pessoas.

Erros do cliente

Código	Status	Significado e o que fazer
validation_failed	400	Um campo não passou na validação. field indica qual; details explica. Corrija o campo.
bad_request	400	A requisição não pôde ser lida: JSON malformado, um fluxo Content-Encoding corrompido, um corpo interrompido. Não há campo a corrigir; verifique o transporte.
validation_error	400	X-Account-Id foi enviado a um endpoint que o proíbe (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	O cursor de paginação tem mais de 24 horas. Recomece a listagem.
unauthenticated	401	Token ausente ou inválido. Renove a sessão ou verifique a chave.
invalid_signature	401	A assinatura de um webhook não foi verificada. Veja Webhooks.
forbidden	403	O token é válido, mas não tem a permissão.
account_context_mismatch	403	X-Account-Id não corresponde à conta do token. A ideia que o cliente tem da empresa atual ficou desatualizada; leia-a novamente da sessão.
not_found	404	O recurso não existe ou pertence a outra conta ou site. A API nunca distingue os dois casos.
conflict	409	Conflito de estado: bloqueio otimista, restrição de unicidade ou uma ação não permitida no estado atual (por exemplo, escrever em uma conversa mesclada).
idempotency_key_conflict	409	A Idempotency-Key foi reutilizada com um corpo diferente.
payload_too_large	413	O corpo excede o limite desta família de endpoints.
unsupported_media_type	415	Content-Type incorreto.
unprocessable	422	JSON válido, mas uma regra de negócio o recusou (por exemplo, um horário de agendamento fora do horário de atendimento).
storage_quota_exceeded	422	A conta atingiu o limite de armazenamento do plano. details traz used_bytes, quota_bytes e requested_bytes; libere espaço ou faça upgrade.
rate_limited	429	Diminua o ritmo. Respeite Retry-After e details.retry_after_seconds.

Erros do servidor

Código	Status	Significado e o que fazer
internal_error	500	Falha inesperada. Tente mais uma vez e depois contate o suporte informando o request_id.
upstream_unavailable	502	O gateway não conseguiu alcançar o serviço. Uma nova tentativa rápida geralmente funciona.
service_unavailable	503	Manutenção programada ou um circuit breaker aberto. Tente de novo após o tempo do cabeçalho Retry-After.
ai_vendor_out_of_funds	503	Seu provedor de IA recusou a chamada por motivos de cobrança (um 402 ou um 429 de cota vindo do fornecedor). Recarregue a conta no fornecedor; uma nova tentativa não vai ajudar.
upstream_timeout	504	O serviço não respondeu a tempo. Tente de novo quando retry_after estiver presente.

Novas tentativas

Repita 429, 502, 503, 504 e falhas de rede com backoff exponencial, e envie a mesma Idempotency-Key na nova tentativa para que uma gravação nunca seja aplicada duas vezes. Não repita 4xx além de 429.