Erros

Toda falha da API responde o mesmo envelope, qualquer que seja o status. Trate pelo campo code.

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agente não encontrado.",
    "details": {},
    "request_id": "req_…"
  }
}

Campo	O que é
`code`	O código estável da falha. É o contrato: compare por igualdade.
`message`	Frase curta em português, para gente. Pode mudar; nunca use como chave.
`details`	Detalhe estruturado, `{}` quando não há. Na validação, `{"field": "name", "reason": "required"}`.
`request_id`	O id desta requisição, igual ao cabeçalho `x-request-id`. Mande-o ao suporte.

Status e códigos

Situação	Status	`code`
Corpo, parâmetro ou JSON inválido	422	`VALIDATION_ERROR`
`Idempotency-Key` obrigatória ausente	400	`IDEMPOTENCY_KEY_REQUIRED`
Sem credencial ou credencial recusada	401	`UNAUTHORIZED`
Sem a capacidade exigida	403	`FORBIDDEN`
Operação exige sessão	403	`SESSION_REQUIRED`
Não existe ou está fora do seu alcance	404	`<RECURSO>_NOT_FOUND`
Conflito de unicidade ou concorrência	409	`CONFLICT`
Transição de estado não permitida	409	`INVALID_STATE_TRANSITION`
Corpo acima do limite	413	`PAYLOAD_TOO_LARGE`
Cliente bloqueado por cobrança	402	`TENANT_BLOCKED`
Limite de requisições	429	`RATE_LIMITED` (respeite `Retry-After`)
Provedor externo indisponível	503	`INTEGRATION_UNAVAILABLE`
Serviço indisponível	503	`SERVICE_UNAVAILABLE`
Tempo esgotado	504	`TIMEOUT`
Falha inesperada	500	`INTERNAL_ERROR`

4xx: em geral, corrija o pedido antes de repeti-lo. Em 409 IDEMPOTENCY_IN_PROGRESS e 429, espere; em 409 IDEMPOTENCY_REPLAY_UNAVAILABLE, consulte o recurso quando disponível, sem tentar recuperar a resposta original pela mesma chave.
5xx e falhas de rede: se a operação declarar Idempotency-Key, repita com a mesma chave; não presuma que a resposta original possa ser reproduzida. Confira os parâmetros da operação e veja Repetição segura.