Respostas e Códigos de Erro

Esta página é a referência canônica do formato de todas as respostas da API SauBit — sucesso e erro. Todos os exemplos abaixo são respostas reais da API de produção.

Formato padrão de erro

Todo erro retorna Content-Type: application/json com um campo detail:

• erros de negócio/autorização → detail é uma string;
• erros de validação de payload (422) → detail é uma lista de problemas por campo.

{ "detail": "API key inválida" }

Tabela de status

HTTP	Quando ocorre	detail (exemplo real)
200	Sucesso	corpo específico da rota
401	API key ausente ou inválida	API key required
403	Key inválida, expirada, IP não liberado ou escopo insuficiente	Scope insuficiente para esta API key
404	Recurso não encontrado (análise, prontuário)	Análise não encontrada
409	Conflito (recurso já existe)	Prontuário já existe para este patient_reference
422	Payload inválido (validação)	lista de erros por campo
429	Limite de requisições excedido	Rate limit excedido
503	Dependência indisponível / serviço ocupado	Serviço ocupado. Tente novamente.
504	Análise excedeu o tempo limite do endpoint	A análise excedeu o tempo limite. Tente novamente em instantes.

---

401 — Não autenticado

API key ausente ou inválida no header X-API-Key.

{ "detail": "API key required" }

403 — Não autorizado

Vários cenários retornam 403, sempre com detail em string:

{ "detail": "API key inválida" }

{ "detail": "API key expirada" }

{ "detail": "IP não permitido para esta API key" }

{ "detail": "Scope insuficiente para esta API key" }

Em rotas com escopo nomeado (ex.: prontuário), a mensagem indica o escopo exigido:

{ "detail": "Escopo insuficiente: requer prontuario:write" }

404 — Não encontrado

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

{ "detail": "Prontuário não encontrado" }

409 — Conflito

{ "detail": "Prontuário já existe para este patient_reference" }

422 — Payload inválido

Validação de schema. detail é uma lista: cada item aponta o campo (loc), o tipo de erro (type) e a mensagem (msg).

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "medications"],
      "msg": "Field required",
      "input": { "language": "pt-BR" }
    }
  ]
}

429 — Limite de requisições

Retornado quando o limite por minuto ou mensal da organização é excedido. Respeite o header Retry-After (quando presente) e aplique backoff exponencial.

{ "detail": "Rate limit excedido" }

503 — Serviço indisponível

Dependência crítica temporariamente indisponível (ex.: rate limiter/cache) ou serviço sob proteção de carga. É seguro repetir a requisição após um curto intervalo.

{ "detail": "Serviço ocupado. Tente novamente." }

504 — Tempo limite

A análise não terminou dentro do tempo limite do endpoint (proteção de carga). Repita a chamada; respostas complete ficam em cache e tendem a retornar rápido na repetição.

{ "detail": "A análise excedeu o tempo limite. Tente novamente em instantes." }

---

Boas práticas de tratamento de erro

• Sempre trate 401/403 como erro de credencial/escopo (não repita sem corrigir).
• Em 422, leia detail[].loc para apontar o campo inválido ao usuário.
• Em 429/503/504, use retry com backoff (ex.: 1s, 2s, 4s) e um teto de tentativas.
• Para a rota de interações, lembre-se da política fail-safe: uma falha técnica nunca rebaixa o risco — confira analysis_status (complete | partial | failed) e source_coverage para saber a completude da análise.