Manejo de errores

La API de Factio devuelve errores en formato JSON consistente.

Estructura de error

{
  "error": {
    "code": "INVALID_RUC",
    "message": "El RUC del emisor no es válido.",
    "detail": "El RUC debe tener 13 dígitos y pasar la validación de módulo 11.",
    "request_id": "req_01HZ3K5X7..."
  }
}

Campo	Descripción
`code`	Código de error interno de Factio. Estable entre versiones.
`message`	Descripción legible del error.
`detail`	Información adicional para debugging.
`request_id`	ID de trazabilidad. Incluirlo siempre al contactar soporte.

Códigos HTTP

HTTP	Cuándo ocurre
`202 Accepted`	Emisión iniciada. No es error.
`400 Bad Request`	Payload inválido, campo faltante o regla fiscal violada.
`401 Unauthorized`	API Key ausente, inválida o revocada.
`403 Forbidden`	La key no tiene permisos para esta operación o recurso.
`404 Not Found`	El recurso solicitado no existe en este tenant.
`409 Conflict`	Idempotency key ya utilizada con payload diferente.
`422 Unprocessable Entity`	Validación de tipos/formatos fallida.
`429 Too Many Requests`	Rate limit excedido. Ver header `Retry-After`.
`503 Service Unavailable`	SRI temporalmente no disponible. Factio reintentará.

Errores de dominio frecuentes

`code`	Descripción	Acción recomendada
`CERTIFICATE_EXPIRED`	El certificado `.p12` del emisor está vencido.	Subir un certificado vigente desde el panel.
`CERTIFICATE_NOT_FOUND`	El emisor no tiene certificado activo.	Subir un certificado `.p12`.
`INVALID_RUC`	RUC del emisor inválido.	Verificar dígito verificador (módulo 11).
`SEQUENCE_EXHAUSTED`	El secuencial de ese establecimiento/punto llegó a `999999999`.	Contactar soporte.
`DUPLICATE_IDEMPOTENCY_KEY`	Key ya usada con payload diferente.	Generar una nueva key.
`SRI_REJECTED`	SRI rechazó el comprobante.	Ver campo `sri_messages` en el recurso del documento.
`ISSUER_DISABLED`	El emisor está deshabilitado en la plataforma.	Revisar configuración en el panel.

Rate limiting

Las solicitudes están limitadas por API Key:

Endpoint	Límite
`POST /documents`	60 requests/minuto
`GET /documents/:id`	300 requests/minuto
`POST /auth/*`	10 requests/minuto

Cuando excedes el límite, la respuesta incluye:

HTTP 429 Too Many Requests
Header Retry-After: N (segundos hasta que puedes reintentar)
Header X-RateLimit-Limit y X-RateLimit-Remaining

Introducción

Conceptos clave

Guías

Manejo de errores

Estructura de error

Códigos HTTP

Errores de dominio frecuentes

Rate limiting

​Estructura de error

​Códigos HTTP

​Errores de dominio frecuentes

​Rate limiting

Estructura de error

Códigos HTTP

Errores de dominio frecuentes

Rate limiting