Manejo de errores

Todos los errores de la API siguen el mismo formato: error es un mensaje legible para humanos y code es el código estable de máquina contra el que debes programar tu lógica.

json

{
  "ok": false,
  "error": "La empresa no tiene folios disponibles para el tipo 33.",
  "code": "NO_FOLIOS"
}

{
  "ok": false,
  "error": "La empresa no tiene folios disponibles para el tipo 33.",
  "code": "NO_FOLIOS"
}

Errores HTTP comunes

Código	Descripción	Qué hacer
`400`	Request inválido (datos faltantes o mal formados)	Revisar el body del request
`401`	No autenticado	Renovar el JWT o verificar la API Key
`403`	Sin permisos	Verificar el rol del usuario o plan
`404`	Recurso no encontrado	Verificar el ID o folio en el path
`409`	Conflicto (ej: folio ya usado)	Verificar el estado actual del recurso
`422`	Validación fallida	El SII rechazó los datos del DTE
`429`	Rate limit superado	Esperar el tiempo indicado en `Retry-After`
`503`	Servicio no disponible	Redis no disponible, reintentar en 30s

Errores de emisión DTE

Cuando el job de emisión falla (estado: "failed"), el campo error del resultado contiene el detalle:

Error	Descripción
`SII_REJECTED`	El SII rechazó el DTE. Ver `detail` para el código SII.
`NO_FOLIOS`	No hay folios disponibles para el tipo de DTE.
`CERT_ERROR`	Error con el certificado digital (vencido o inválido).
`XML_SIGN_ERROR`	Error al firmar el XML. Verificar el certificado.

Reintentos

La API no reintenta automáticamente los requests fallidos del cliente. Sin embargo, Folyo reintenta el envío al SII de forma automática antes de marcar el job como failed.

Para los webhooks, Folyo reintenta la entrega hasta 5 veces con backoff exponencial.