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 o límite del plan alcanzado	Verificar el rol del usuario; si el `code` es `PLAN_LIMIT`, ver Límites del plan
`404`	Recurso no encontrado	Verificar el ID o folio en el path
`409`	Conflicto: folio ya usado, o el SII rechazó una solicitud de folios	Verificar el estado actual del recurso; si el `code` es de folios, ver Errores al solicitar folios
`410`	Archivo expirado (plan gratuito)	Si el `code` es `XML_EXPIRADO`, ver Expiración de archivos
`422`	Validación fallida	El SII rechazó los datos del DTE
`429`	Rate limit superado (`RATE_LIMITED`)	Esperar el tiempo indicado en `Retry-After`. Las descargas de PDF y XML tienen un límite propio de 20 peticiones por ventana de 4 segundos por cuenta: guarda el archivo en vez de volver a pedirlo
`503`	Servicio no disponible	Reintentar según `Retry-After`. `FOLIOS_REQUESTING`: no había folios y Folyo los está pidiendo al SII. `PDF_BUSY`: demasiadas generaciones de PDF en curso; los PDF ya generados siguen descargándose

Límites del plan

Aparte del rate limit HTTP (429), cada plan tiene cuotas mensuales: emisión de DTEs, boletas, consultas al SII, usuarios, empresas y API keys. Cuando alcanzas un tope, o pides algo que tu plan no incluye, la API responde 403 con el código estable PLAN_LIMIT:

json

{
  "ok": false,
  "error": "Límite de consultas mensuales alcanzado. Actualice su plan.",
  "code": "PLAN_LIMIT"
}

{
  "ok": false,
  "error": "Límite de consultas mensuales alcanzado. Actualice su plan.",
  "code": "PLAN_LIMIT"
}

A diferencia del 429, esto no se resuelve esperando unos segundos: el contador de cada período se reinicia al inicio del próximo mes (hora de Chile), o subes de plan. Distingue PLAN_LIMIT (403, cupo del plan agotado) de 429 (ráfaga de requests, se recupera solo) por el code, no por el status.

Los planes que no incluyen boletas (gratuitos) reciben PLAN_LIMIT también al solicitar o cargar folios de boleta (tipos 39 y 41), antes de que Folyo contacte al SII: así no se consume cupo de timbraje para documentos que el plan no puede emitir.

La cuota de consultas al SII cubre las llamadas que Folyo hace por ti a servicios externos de pago por uso (consulta de contribuyente, situación tributaria, sincronización del RCV, estado de DTE, folios, RCOF, acuse, extracción con IA). Emitir DTEs no descuenta de esta cuota; tiene la suya. Cada respuesta sujeta a cuota trae los headers X-Quota-Limit, X-Quota-Remaining y X-Quota-Period. Revisa Rate limits y cuotas para el detalle de qué llamadas consumen cuota.

Errores al solicitar folios

POST /v1/dte/folios/solicitar conversa con el portal de timbraje del SII. Cuando el SII no entrega el rango, la API responde 409 con uno de estos códigos y, en error, el motivo que envió el SII:

Código	Qué significa	Qué hacer
`FOLIOS_BOLETA_SISTEMA_SII`	La empresa emite boletas con el sistema gratuito del SII, que no entrega folios de boleta a software de mercado.	Cambiar la modalidad de emisión de boletas en el sitio del SII y volver a solicitar.
`TIMBRAJE_NO_AUTORIZADO`	El SII bloquea el timbraje: quedan folios sin usar del rango anterior o el contribuyente tiene situaciones pendientes.	Consumir o anular los folios pendientes, o regularizar la situación en el SII.
`FOLIOS_RECHAZADOS_SII`	Cualquier otro rechazo del portal. `error` trae la glosa o el código del SII (por ejemplo `ST-RS-DTE-15-1`).	Revisar la situación tributaria y que el titular del certificado esté autorizado para timbrar por la empresa; si se repite, escribir a soporte con el motivo.

Si la empresa no tiene certificado o le faltan credenciales del SII, la respuesta es 422 con CERT_NOT_CONFIGURED, CERT_UNREADABLE o CONFIG_INCOMPLETE. Ninguno de estos casos consume cuota ni folios.

Expiración de archivos en el plan gratuito

En el plan gratuito, la descarga del XML firmado y del PDF de cada documento está disponible solo por un tiempo desde la emisión. En los planes de pago los archivos no expiran.

Ambiente del documento	Descarga disponible por
Producción	4 horas
Certificación	30 minutos

Pasada la ventana, GET /v1/dte/xml/:tipo/:folio y GET /v1/dte/pdf/:tipo/:folio responden 410 con el código estable XML_EXPIRADO (el PDF comparte el código porque se genera a partir del XML):

json

{
  "ok": false,
  "error": "El XML del DTE tipo 33 folio 1001 ya no está disponible: el plan gratuito lo conserva por 4 horas desde la emisión (30 minutos si es del ambiente de certificación). El documento sigue emitido y vigente ante el SII; no vuelva a emitirlo. Los planes de pago conservan los XML sin límite de tiempo.",
  "code": "XML_EXPIRADO"
}

{
  "ok": false,
  "error": "El XML del DTE tipo 33 folio 1001 ya no está disponible: el plan gratuito lo conserva por 4 horas desde la emisión (30 minutos si es del ambiente de certificación). El documento sigue emitido y vigente ante el SII; no vuelva a emitirlo. Los planes de pago conservan los XML sin límite de tiempo.",
  "code": "XML_EXPIRADO"
}

Dos cosas importantes:

El documento no desaparece: solo expira la descarga. El DTE sigue emitido y vigente ante el SII, con su folio consumido, y lo sigues viendo en el listado de documentos con montos, receptor y estado. No vuelvas a emitirlo: duplicarías el documento ante el SII.
Guarda los archivos al emitir. El resultado del job de emisión y el webhook dte.emitido llegan dentro de la ventana: descarga el XML y el PDF apenas el job termina y almacénalos de tu lado. Si necesitas re-descargar más adelante, cualquier plan de pago conserva los archivos sin expiración.

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.
`ENVIO_DTE_INCIERTO`	En una compra internacional, Folyo no pudo comprobar el acuse del SII. Revisa el job antes de reintentar; no reemitas ni reserves otro folio.

ENVIO_DTE_INCIERTO no incluye un XML candidato en la respuesta. El sobre pudo haber llegado al SII, por lo que primero se debe revisar el mismo job y resolver su estado antes de cualquier nueva emisión.

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. Si el SII confirmó el envío y luego falla una persistencia local, Folyo recupera esa persistencia con el mismo resultado: no envía otro sobre ni asigna otro folio.

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