Códigos de erro e diagnóstico
Erros de aplicação usam um código estável em inglês e uma mensagem em português. O cliente deve decidir o fluxo pelo code e pelo status HTTP, usando message para orientar a pessoa.
{
"code": "permission_denied",
"message": "Você não tem permissão para esta ação.",
"request_id": "identificador-da-requisicao"
}
A frase acima é ilustrativa; o catálogo de tradução da versão do servidor fornece a mensagem exata. Campos adicionais podem trazer detalhes específicos do módulo.
Códigos comuns
| Status | Código | Ação esperada |
|---|---|---|
| 400 | validation_error | Corrigir o formato ou o conteúdo enviado |
| 400 | listing_invalid | Revisar filtro, campo, operador, ordenação ou cursor |
| 401 | unauthenticated | Verificar a sessão ou credencial pelo fluxo correto |
| 401 | origin_not_allowed | Retirar a chave de integração do cliente de navegador |
| 403 | permission_denied | Revisar a permissão e o papel do ator |
| 403 | actor_not_allowed | Usar o tipo de ator exigido pela operação |
| 403 | membership_inactive | Verificar o vínculo com a organização |
| 403 | password_change_required | Concluir a troca obrigatória de senha |
| 403 | mfa_enrollment_required | Concluir o cadastro de MFA exigido |
| 403 | mfa_challenge_required | Validar o segundo fator da sessão |
| 403 | recent_login_required | Reautenticar para a ação sensível |
| 404 | not_found | Confirmar código, organização e escopo do recurso |
| 409 | idempotency_conflict | Não reutilizar a chave para outra solicitação |
| 409 | concurrency_conflict | Aguardar, reler o estado e repetir se ainda adequado |
| 503 | unavailable | Preservar a sessão e respeitar Retry-After |
Uma rota de domínio pode usar outros códigos e status. Consulte também a mensagem retornada e as regras da operação.
Validação de campos
Nas rotas Audience, falhas de validação retornam 422 com o envelope validation_error, request_id e errors. Nas rotas de equipe, a validação de schema mantém o formato detail do FastAPI, sem o valor bruto de entrada.
O consumidor precisa tratar os dois contratos. Não exiba uma resposta inteira de validação como texto técnico para o usuário; associe o problema ao campo quando possível.
Limites e indisponibilidade
Uma resposta 429 indica limite de frequência e pode trazer Retry-After. Não repita em laço imediato. Um 409 concurrency_conflict traz Retry-After: 1; indisponibilidade mapeada de banco traz 503 unavailable e Retry-After: 5.
A indisponibilidade não significa credencial inválida. Encerrar sessões em qualquer resposta de erro transforma uma interrupção transitória em perda de acesso desnecessária.
Solicitar suporte
Informe horário com fuso, método, caminho sem dados sensíveis, status, code e request_id. Acrescente o código público do recurso quando necessário. Remova autorização, cookies, documentos pessoais e URLs assinadas da evidência compartilhada.
Veja idempotência, auditoria e sessões.