Respostas e erros
Identifique o resultado da chamada e saiba qual ação executar.
Status HTTP
2xx indica uma chamada aceita. 400 ou 422 indica parâmetros inválidos. 401 indica chave ausente, expirada ou inválida. 403 indica falta de permissão ou recurso não autorizado. 404 indica recurso ou rota não encontrado. 409 indica conflito. 429 indica limite de chamadas. 5xx indica falha temporária do serviço ou de uma dependência.
Referência de suporte
Quando a resposta incluir erro.id ou o cabeçalho x-portal-erro-id, registre essa referência junto do horário, método, caminho e status HTTP. O suporte usa esses dados para localizar a falha. Não envie chaves ou dados privados em relatórios de erro.
Retentativas
Em consultas GET, use espera progressiva para falhas temporárias e respeite Retry-After quando ele estiver presente. Não repita 401 ou 403 em loop; corrija a chave ou a permissão. Não trate um erro de rede como uma resposta vazia. Um timeout não comprova que uma operação foi executada.
Exemplo de formato de erro
O formato abaixo é ilustrativo. Use o schema e a resposta real da operação selecionada.
{
"detail": "Você não tem permissão para esta ação.",
"erro": {
"codigo": "SEM_PERMISSAO",
"status": 403,
"id": "<referencia-da-chamada>"
}
}