Códigos de erro

1. Status HTTP

2. Códigos AUTH_* (autenticação HMAC)

Todos retornam 401 exceto AUTH_INSUFFICIENT_SCOPE (403) e OPERATION_NOT_ALLOWED (403).

3. Códigos VAL_* e RES_* (validação / recurso)

4. Códigos BACKEND_* (problemas no backend Sivoe)

5. Códigos de escrita (Agenda — Fase 4b; Pacientes — Fase 3*)

Aparecem nos 3 POST de agenda (criar, cancelar, reagendar) e nos 3 endpoints de escrita de paciente (POST /v1/pacientes, PATCH /v1/pacientes/{id} e POST /v1/pacientes/unificar). Contrato completo de idempotência em referência § Idempotência. CPF_ALREADY_EXISTS e MEDICAL_RECORD_ALREADY_EXISTS são exclusivos da Fase 3* (Pacientes); PACIENTES_UNIFICACAO_MESMO_ID é exclusivo da unificação.

6. Códigos de resolução de alias (1.1.0)

Disponíveis na release 1.1.0, no POST /v1/exames. Quando você envia identificadores de negócio (aliases — paciente_cpf, convenio_nome, procedimento_abreviacao, medico_exame_crm etc.) em vez do *_id interno, o gateway resolve cada alias para o *_id correspondente. Se a resolução falha, devolve um 422 acionável. Todos os 3 códigos são consolidados num único envelope (veja §7) — o gateway não aborta no primeiro erro; reporta todos os campos de uma vez.

Envelope consolidado (M4)

O error.details agrega todos os campos que falharam:

• details.field — o field do primeiro item da lista (atalho).
• details.lista[] — um item por campo com problema. Cada item carrega field, code e msg (a mensagem do campo — é msg, não value). Conforme o caso, também: candidatos[] (em RESOLUTION_AMBIGUOUS), id_informado + id_resolvido (em PARAM_CONFLICT), e os campos de enriquecimento fonte (onde descobrir o valor), alias_aceito (alias que evita mandar o *_id) e valores_aceitos (enum, para campos de domínio fechado como prioridade ou requer_laudo).
• details.candidatos — atalho no topo com os candidatos; só aparece quando algum item é RESOLUTION_AMBIGUOUS.

{
  "data": null,
  "meta": { "request_id": "1a2b3c4d5e6f", "duracao_ms": 47 },
  "error": {
    "code": "RESOLUTION_AMBIGUOUS",
    "message": "2 campos precisam de atencao.",
    "details": {
      "field": "convenio_nome",
      "lista": [
        { "field": "convenio_nome", "code": "RESOLUTION_AMBIGUOUS",
          "msg": "Encontrado mais de um convenio com o mesmo nome.",
          "candidatos": [ { "id": 31, "nome": "UNIMED" }, { "id": 88, "nome": "UNIMED" } ],
          "fonte": "GET /v1/convenios", "alias_aceito": "convenio_nome" },
        { "field": "medico_exame_crm", "code": "RESOLUTION_NOT_FOUND",
          "msg": "Medico de exame nao localizado para o CRM informado.",
          "fonte": "GET /v1/medicos?papel=EXAME", "alias_aceito": "medico_exame_crm" }
      ],
      "candidatos": [ { "id": 31, "nome": "UNIMED" }, { "id": 88, "nome": "UNIMED" } ]
    }
  }
}

400 (validação) vs 422 (resolução) no POST /v1/exames

Os dois caminhos de erro do POST /v1/exames usam o mesmo envelope que ensina (details.field + details.lista[] com field/msg e o enriquecimento fonte/alias_aceito) — diferem apenas no status e no code. Em particular, o 400 VAL_INVALID_PARAM não é um 400 "seco": quando você omite um campo obrigatório que não tem default no tenant, a details.lista[] traz fonte e alias_aceito de cada campo faltante.

Exemplo de 400 com a lista que ensina (obrigatório omitido, tenant sem default):

{
  "data": null,
  "meta": { "version": "1.1.0", "timestamp": "2026-06-19T10:00:00-03:00" },
  "error": {
    "code": "VAL_INVALID_PARAM",
    "message": "2 campos precisam de atencao.",
    "details": {
      "field": "unidade_id",
      "lista": [
        { "field": "unidade_id", "msg": "Obrigatorio (sem default no tenant).",
          "fonte": "GET /v1/unidades", "alias_aceito": "unidade_nome" },
        { "field": "medico_exame_id", "msg": "Obrigatorio (sem default no tenant).",
          "fonte": "GET /v1/medicos?papel=EXAME", "alias_aceito": "medico_exame_crm" }
      ]
    }
  }
}

7. Envelope padrão de erro

Toda resposta de erro segue exatamente este formato. data sempre null em erro; error.code é o identificador estável; error.message é texto em português (PT-BR sem acentos especiais para evitar problemas de encoding); error.details pode trazer info estruturada (ex.: field no VAL_INVALID_PARAM).

{
  "data":  null,
  "meta":  {
    "request_id": "a1b2c3d4e5f6",
    "duracao_ms": 12
  },
  "error": {
    "code":    "AUTH_INVALID_SIGNATURE",
    "message": "Assinatura HMAC invalida.",
    "details": null
  }
}

8. Headers padronizados em toda resposta

Independente de status, toda resposta carrega:

X-Api-Version: v1
X-Content-Type-Options: nosniff
Cache-Control: no-store

• X-Api-Version permite ao integrador detectar mudança de versão (você pode pinning seu cliente).
• X-Content-Type-Options: nosniff impede MIME sniffing — defesa em profundidade.
• Cache-Control: no-store sinaliza explicitamente que respostas autenticadas não devem ser cacheadas em proxies intermediários.