Tratamento de erros

A API usa códigos HTTP padrão. Trate-os de forma robusta na sua integração.

Envelope de negócio: 200 OK não garante sucesso

Vários endpoints de escrita retornam HTTP 200 mesmo quando a operação falhou por uma regra de negócio — o erro vem no corpo, não no status: { "success": false, "message": "...", "data": {...} }. Exemplo real: POST /v3/correcoes com um anomaliaId que não existe responde 200 OK com "success": false e "message": "Ocorrência não encontrada".

Não confie só no status HTTP

Sua integração precisa checar o campo success do corpo em todo endpoint de escrita, mesmo quando o status é 200. Tratar 200 como sinônimo de sucesso vai deixar erros de negócio passarem silenciosamente. Quando success: false, inspecione também data — em validações condicionais (ex.: aprovação de ocorrência), é ali que a API detalha quais campos faltaram.

Códigos comuns

Código	Significado	Ação recomendada
200 OK	Sucesso.	—
400 Bad Request	Requisição inválida (ex.: ocorrência típica inválida, payload malformado).	Revise o corpo/parâmetros. A mensagem indica a causa.
401 Unauthorized	Token ausente, expirado ou inválido.	Reautentique no AuthCenter.
403 Forbidden	Autenticado, sem permissão para o recurso/empresa.	Verifique o escopo do usuário.
404 Not Found	Recurso inexistente.	Confirme o identificador.
429 Too Many Requests	Limite de taxa excedido.	Aguarde e reenvie (ver Rate limiting).
500 Internal Server Error	Erro no servidor.	Reenvie com backoff; se persistir, contate o suporte.

Exemplos de validação de domínio

Algumas validações retornam 400 com mensagem específica:

Cenário	Mensagem
AnomaliaTipicaId de outra empresa ou inexistente	"Ocorrência típica inválida"

StatusIds inválido retorna 500, não 400

Testado: enviar um valor não numérico em StatusIds (ex.: StatusIds=abc) retorna 500 Internal Server Error com mensagem genérica "Unexpected Error", em vez do 400 Bad Request esperado para erro de validação de entrada. Esse é o comportamento atual — está em correção pelo time de backend. Enquanto isso, trate um 500 inesperado em StatusIds como possível erro de formato do valor enviado, não só como falha do servidor.

Boas práticas

• Implemente retry com backoff exponencial para 429 e 5xx.
• Não faça retry automático em 400/401/403 — são erros de cliente que exigem correção.
• Registre o traceId/correlação quando disponível para suporte (a API usa monitoramento de erros interno).