Erros

Toda resposta de erro da API — em qualquer domínio — segue o mesmo formato simples:

{ "detail": "Análise não encontrada." }

Códigos de status comuns

Status	Significado	Corpo típico
`401`	Falha de autenticação — veja Autenticação.	`{"detail": "Falha na autenticação."}`
`403`	A chave é válida, mas não tem o escopo necessário.	`{"detail": "Escopo insuficiente."}`
`404`	O recurso solicitado não existe.	`{"detail": "Análise não encontrada."}` (mensagem varia por domínio)
`409`	Conflito — geralmente uma identidade de subject ambígua.	`{"detail": "A resolução de identidade do sujeito é ambígua."}`
`422`	Requisição inválida — corpo, parâmetro de rota, query, ou regra de negócio.	Ver abaixo.
`429`	Limite de uso (quota) do plano foi excedido.	`{"detail": "quota_exceeded"}`
`503`	Um recurso dependente está temporariamente indisponível.	`{"detail": "A resolução de identidade do sujeito está temporariamente indisponível."}`

Alguns endpoints do domínio de grafo, adicionados mais recentemente, ainda retornam mensagens em inglês (ex.: "Graph node was not found."). É uma inconsistência conhecida no back-end, não um erro desta documentação — o formato {"detail": "<mensagem>"} continua o mesmo.

Endpoints que criam recursos cobráveis (POST /analyses, POST /reports, POST /adverse-media) passam por uma checagem de limite de plano antes de executar a operação. Além dos erros de domínio documentados em cada página, eles também podem retornar 429 com {"detail": "quota_exceeded"} (limite de uso do período esgotado) ou 403 com {"detail": "feature_not_in_plan"} (o plano atual não inclui esse recurso) — este 403 é distinto do 403 de escopo insuficiente da tabela acima, embora tenha o mesmo status HTTP.

O caso especial do `422`

Diferente dos demais, 422 Unprocessable Entity não usa o formato {"detail": "<string>"} — ele segue o formato padrão de validação do FastAPI, uma lista de erros por campo:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "name"],
      "msg": "Pelo menos um entre 'name' ou 'document' deve ser fornecido.",
      "input": null
    }
  ]
}

Trate detail como string nos demais status, e como lista de objetos apenas em 422.

Primeiros passos

Conceitos

Códigos de status comuns

O caso especial do `422`

​Códigos de status comuns

​O caso especial do 422

Códigos de status comuns

O caso especial do `422`