Erros
Envelope de erro, códigos estáveis e como tratá-los.
Toda resposta de erro tem o mesmo formato, com mensagem em português:
{
"error": {
"code": "invalid_request",
"message": "Requisição inválida.",
"details": [{ "path": "citacoes", "message": "Muito pequeno: esperado que array tivesse >=1 itens" }]
}
}details é opcional e varia por código. Programe contra code, não contra message.
| HTTP | code | Quando | O que fazer |
|---|---|---|---|
| 400 | invalid_request | Corpo, query ou path fora do schema. details[] lista path e message. | Corrigir a requisição |
| 401 | unauthorized | Rota exige chave; chave em formato inválido; chave desconhecida ou desativada. | Enviar Authorization: Bearer vg_live_… válido |
| 404 | not_found | Diploma, artigo, dispositivo ou súmula inexistente; rota desconhecida. | Verificar sigla/ref_key. No /resolver isso não é erro: vira status |
| 429 | rate_limited | Limite por minuto ou mensal atingido. Retry-After e details.janela (1m/mes). | Esperar Retry-After; ver limites |
| 502 | upstream_error | Falha ao consultar fonte externa. | Repetir com backoff |
| 503 | (sem code) | GET /v1/health com status: "degraded" quando o banco não responde. | Repetir; conferir o status |
| 500 | internal_error | Erro inesperado. Registrado com o X-Request-Id da resposta. | Repetir; informar o X-Request-Id no suporte |
Exemplos:
{ "error": { "code": "unauthorized", "message": "Esta rota exige chave de API. Envie Authorization: Bearer vg_live_..." } }{ "error": { "code": "not_found", "message": "Diploma \"XYZ\" não está no corpus." } }Citação inválida não é erro HTTP
No /v1/resolver e no /v1/resolver-texto, uma citação que não existe não gera 404: a resposta é
200 e o item correspondente vem com status: "nao_encontrado" (ou diploma_desconhecido,
revogado, cancelada, verificado_parcial). Veja Verificação → Status.
X-Request-Id
Toda resposta traz X-Request-Id. Você pode enviar o seu próprio no cabeçalho da requisição; ele é
propagado para os logs do servidor e devolvido, o que facilita correlacionar um incidente.