Erros

Toda resposta de erro usa um envelope JSON estável.

aviso

Ramifique sua lógica pelo code, nunca pelo texto de message — a mensagem é legível por humanos e pode mudar; o code é contrato.

Envelope

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Request body validation failed.",
    "details": {
      "issues": [
        { "path": "amount", "code": "invalid_string", "message": "Invalid" }
      ]
    }
  }
}

Campo	Descrição
error.code	Código estável (tabela abaixo). Ramifique por ele.
error.message	Texto legível, em inglês. Não parseie.
error.details	Presente em alguns erros — dados estruturados úteis (campo ofensor, motivo, escopo faltante). Ver exemplos abaixo.

Códigos

code	HTTP	Quando
bad_request	400	Query/body malformado — JSON inválido, filtro/operador desconhecido, cursor inválido, valor de filtro vazio, limit inválido.
invalid_token	401	Token ausente, malformado, assinatura inválida ou expirado.
invalid_audience	401	A aud do token não é aceita.
token_revoked	401	Token revogado.
insufficient_scope	403	Token válido, mas sem o escopo exigido. details traz required e granted.
unknown_organization	403	O sub do token não corresponde a nenhum workspace.
not_found	404	Recurso inexistente ou fora do seu workspace — por isolamento, um recurso de outro tenant lê como 404.
conflict	409	Conflito de estado: X-Idempotency-Key reusada com corpo diferente, requisição idêntica ainda em andamento, ou corrida em uma constraint única. details.reason quando aplicável.
unprocessable_entity	422	Corpo válido, mas os dados violam uma regra — validação de schema, referência (FK) fora do tenant, ou transição de estado inválida. details.issues na validação de schema.
rate_limited	429	Limite de requisições atingido. Ver Limite de Requisições.
internal_error	500	Falha inesperada no servidor. Nunca carrega details. Reenvie com backoff.

Exemplos de details

Validação de schema (422):

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Request body validation failed.",
    "details": {
      "issues": [
        { "path": "amount", "code": "invalid_string", "message": "Invalid" }
      ]
    }
  }
}

Escopo insuficiente (403):

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token is missing required scope: finance.payables.dispatch.",
    "details": {
      "required": "finance.payables.dispatch",
      "granted": ["finance.payables"]
    }
  }
}

Idempotency-Key reusada com corpo diferente (409):

{
  "error": {
    "code": "conflict",
    "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key.",
    "details": { "reason": "idempotency_key_reused" }
  }
}