Errores

La API responde con códigos HTTP estándar. Cualquier respuesta fuera del rango 2xx contiene un objeto error con código legible por máquina, mensaje en español para humanos y detalles opcionales.

Estructura

json

{
  "error": {
    "code": "validation_failed",
    "message": "El campo 'total_amount' es obligatorio.",
    "details": {
      "field":   "total_amount",
      "reason":  "missing"
    }
  }
}

Códigos HTTP

Código	Significado	Cuándo
200	OK	Operación correcta.
201	Created	Recurso creado.
204	No content	DELETE correcto, sin body.
400	Bad request	JSON malformado o tipo incorrecto.
401	Unauthorized	API key ausente o revocada.
403	Forbidden	Tu key no tiene el scope requerido.
404	Not found	El recurso no existe o no pertenece a tu organización.
409	Conflict	Conflicto de estado (ej. factura duplicada).
422	Validation failed	Los datos pasan los tipos pero no las reglas de negocio.
429	Too many requests	Has superado el rate limit.
500	Server error	Error interno. Reintenta con backoff.
503	Service unavailable	Mantenimiento o sobrecarga. Reintenta.

Catálogo de códigos

`error.code`	HTTP	Descripción
`missing_api_key`	401	Falta la cabecera `Authorization`.
`api_key_revoked`	401	La key se ha revocado desde el panel.
`insufficient_scope`	403	Tu key no incluye el scope requerido.
`resource_not_found`	404	El ID no existe en tu organización.
`validation_failed`	422	Un campo no cumple las reglas (ver `details`).
`duplicate_resource`	409	Ya existe un recurso equivalente (ej. factura con mismo nº y proveedor).
`rate_limit_exceeded`	429	Has superado tu cuota.
`internal_error`	500	Algo se rompió de nuestro lado. Reintenta.

Ejemplo: validación

json

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "code": "validation_failed",
    "message": "Hay 2 campos con errores.",
    "details": {
      "fields": [
        { "field": "invoice_number", "reason": "required" },
        { "field": "total_amount",   "reason": "must_be_positive" }
      ]
    }
  }
}

Recomendaciones

No filtres por message en tu código — puede cambiar. Filtra siempre por error.code.
Loguea el X-Request-Id de las respuestas: nos lo pides al abrir un ticket y rastreamos el log al instante.
Si recibes 500 o 503, reintenta con backoff exponencial (1s, 2s, 4s…) hasta 3 veces.