Errores y códigos HTTP | API de facturación electrónica

La API usa códigos HTTP estándar y, para los errores con detalle por campo, el formato application/problem+json (RFC 7807). Esta página es la referencia única de qué significa cada código y qué hacer al recibirlo.

Códigos HTTP

Código	Significado	Acción sugerida
200 OK	Operación exitosa.	Procesa el cuerpo en `data`.
201 Created	Recurso creado correctamente.	Lee `data.id` para futuras llamadas.
204 No Content	Operación exitosa sin cuerpo (eliminación).	No intentes parsear JSON.
400 Bad Request	Petición mal formada (JSON inválido, tipo incorrecto, parámetro faltante).	Revisa el cuerpo y los headers antes de reintentar.
401 Unauthorized	API Key ausente, inválida o inactiva.	Verifica el header `X-API-Key`. Si la clave fue desactivada, genera una nueva.
403 Forbidden	Tu plan no incluye API, tu IP no está autorizada, o alcanzaste un límite del plan (comercios, establecimientos o puntos de emisión).	Actualiza tu plan, ajusta la whitelist de IPs, o desactiva recursos que ya no uses para liberar cupo.
404 Not Found	El recurso solicitado no existe o no pertenece a tu cuenta.	Verifica el `id` y el `businessId`.
409 Conflict	Conflicto de estado (ej. emitir un documento ya emitido).	Consulta el estado actual con `GET /{resource}/{id}` antes de reintentar.
422 Unprocessable Entity	Validación fallida. El cuerpo contiene una lista de errores por campo en `errors`.	Corrige los campos indicados y reenvía.
429 Too Many Requests	Excediste el cupo de la ventana actual.	Espera los segundos indicados en `Retry-After`.
500 Internal Server Error	Error inesperado del servidor.	Reintenta con backoff. Si persiste, contacta a soporte con el `instance` del payload.
503 Service Unavailable	Servicio temporalmente no disponible (típicamente firma electrónica o SRI caídos).	Reintenta con backoff exponencial. No es un fallo de tu petición.

Forma de los errores

Error de validación (RFC 7807)

json

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "El campo customer_id es obligatorio.",
  "errors": [
    { "field": "customer_id", "message": "El campo customer_id es obligatorio." }
  ]
}

Error simple

json

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{ "error": "Too many requests" }

Estrategia de reintento

Reintenta automáticamente solo en estas condiciones:

429 — respeta Retry-After.
500, 502, 503, 504 — con backoff exponencial (1 s, 2 s, 4 s…) hasta 5 intentos.
Errores de red (timeout, DNS) — backoff similar.

No reintentes automáticamente 4xx distintos de 429: indican un error en tu petición.

Errores comunes y cómo resolverlos

Síntoma	Causa probable	Solución
`401 "API Key is missing"`	Olvidaste el header `X-API-Key`.	Añádelo a tu cliente HTTP por defecto.
`403 "API access not included"`	Tu plan actual no permite API.	Sube de plan desde tu suscripción.
`422 "document_type_id es obligatorio"`	Falta `document_type_id` en el body de `POST /documents`.	Incluye el ID del tipo de comprobante (ver `/catalogs/document-types`).
`422` en firma del SRI	Firma electrónica `.p12` vencida o contraseña incorrecta.	Renueva el archivo desde `PATCH /businesses/{id}/files`.
`503` en emisión	El SRI no respondió.	Reintenta y, si el comprobante quedó en estado `recepted`, usa `PUT /documents/{id}` con `{ "verify": true }`.