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": "VALIDATION_ERROR",
    "message": "Request body validation failed.",
    "details": {
      "issues": [
        { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" }
      ]
    }
  }
}

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: requisição idêntica ainda em andamento, ou corrida em uma constraint única.
IDEMPOTENCY_KEY_REUSED	409	X-Idempotency-Key reusada com um corpo diferente. Reenvie os parâmetros originais ou gere uma chave nova.
VALIDATION_ERROR	422	O corpo não satisfaz o schema — campo ausente, tipo errado, chave desconhecida. details.issues diz onde. Reenviar o mesmo corpo não adianta.
UNPROCESSABLE_ENTITY	422	Corpo bem-formado que o domínio recusou — FK fora do tenant, transição de estado inválida. Pode passar quando o estado mudar.
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": "VALIDATION_ERROR",
    "message": "Request body validation failed.",
    "details": {
      "issues": [
        { "path": "amount", "code": "invalid_type", "message": "Expected number, received string" }
      ]
    }
  }
}

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": "IDEMPOTENCY_KEY_REUSED",
    "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key."
  }
}