Docs / Errores
Empezar

Errores

La API usa códigos HTTP estándar y devuelve un body JSON consistente con un code legible y un message humano.

Formato del body

{
  "code": "factura_rechazada",
  "message": "El ente tributario rechazó el comprobante.",
  "request_id": "req_01HXYZ...",
  "details": {
    "motivo": "RUC del cliente no autorizado"
  }
}

Siempre incluimos un request_id para que puedas pasárnoslo al pedir soporte y trazar la petición en nuestros logs.

Códigos HTTP

Status Nombre Cuándo ocurre
400 Bad Request Body malformado, validación de schema fallida.
401 Unauthorized Falta la API key, es inválida, o está revocada.
403 Forbidden La key existe, pero su rol no permite este endpoint o recurso.
404 Not Found El recurso (factura, cliente, workflow) no existe para tu organización.
409 Conflict Conflicto de estado (por ejemplo, reenviar una factura ya AUTORIZADA).
422 Unprocessable Validación de negocio fallida (RUC inválido, total ≤ 0, etc.).
429 Too Many Requests Excediste el rate limit. Mira el header Retry-After.
500 Server Error Error inesperado nuestro. Reintenta con backoff o avísanos.
503 Service Unavailable Mantenimiento o incidente en curso. Retry-After indica cuándo reintentar.

Errores de negocio

Para errores de negocio mantenemos códigos estables que puedes parsear en tu cliente sin tener que casar con el mensaje (que puede cambiar).

code Significado
cliente_no_encontradoEl RUC/cédula no existe en la base del ente tributario.
factura_rechazadaEl ente tributario rechazó el comprobante; ver details.motivo.
certificado_invalidoEl .p12 del emisor está expirado o la contraseña no coincide.
idempotency_conflictReusaste un Idempotency-Key con un body distinto.
cuota_excedidaSuperaste el cupo anual de tu plan (Gratis: 200 comprobantes/año; Negocio: 6.000/año). El API responde 402 — las lecturas y descargas nunca se bloquean.
workflow_invalidEl grafo del workflow tiene un nodo sin configurar o un ciclo.

Rate limits

Todos los planes: 120 requests/minuto por API key (fair use técnico, no facturable). Para límites mayores en el plan Empresarial, contacta a ventas. 

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1719700060

Backoff exponencial con jitter

Para errores 429 y 5xx, recomendamos esperar min(2^intento * 250ms ± 100ms jitter). Los SDKs ya lo hacen por ti; si usas cURL u otro cliente, configura el retry manualmente.

¿Encontraste un error raro?

Si recibes un 500 o un code que no está en la tabla, escríbenos por WhatsApp con el request_id. Lo revisamos en menos de 30 minutos en horario laboral.

Anterior ← SDKs