Errores

Toda respuesta de error usa un envoltorio JSON estable.

aviso

Ramifica tu lógica por el code, nunca por el texto de message — el mensaje es legible por humanos y puede cambiar; el code es contrato.

Envoltorio

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

Campo	Descripción
error.code	Código estable (tabla abajo). Ramifica por él.
error.message	Texto legible, en inglés. No lo parsees.
error.details	Presente en algunos errores — datos estructurados útiles (campo ofensor, motivo, alcance faltante). Ver ejemplos abajo.

Códigos

code	HTTP	Cuándo
bad_request	400	Query/body malformado — JSON inválido, filtro/operador desconocido, cursor inválido, valor de filtro vacío, limit inválido.
invalid_token	401	Token ausente, malformado, con firma inválida o expirado.
invalid_audience	401	El aud del token no es aceptado.
token_revoked	401	Token revocado.
insufficient_scope	403	Token válido, pero sin el alcance exigido. details trae required y granted.
unknown_organization	403	El sub del token no corresponde a ningún workspace.
not_found	404	Recurso inexistente o fuera de tu workspace — por aislamiento, un recurso de otro tenant se lee como 404.
conflict	409	Conflicto de estado: X-Idempotency-Key reutilizada con cuerpo diferente, solicitud idéntica aún en curso, o carrera en una constraint única. details.reason cuando aplica.
unprocessable_entity	422	Cuerpo válido, pero los datos violan una regla — validación de schema, referencia (FK) fuera del tenant, o transición de estado inválida. details.issues en la validación de schema.
rate_limited	429	Límite de solicitudes alcanzado. Ver Límite de Solicitudes.
internal_error	500	Falla inesperada en el servidor. Nunca lleva details. Reenvía con backoff.

Ejemplos de details

Validación de schema (422):

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

Alcance 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 reutilizada con cuerpo 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" }
  }
}