Códigos

Los códigos de error que devuelve la API y los códigos de rechazo del SII, con su causa y si conviene reintentar.

Códigos de la API

Agrupados por dónde te los vas a encontrar.

Autenticación y permisos

Código	HTTP	Causa
`insufficient_scope`	403	A la llave le falta un scope; `error.message` nombra cuál
`empresa_required`	400	Falta el header `Facturia-Empresa` en una llamada con alcance de empresa
`empresa_not_allowed`	403	La empresa está fuera de la lista blanca de la llave
`empresa_mismatch`	400	Mandaste `Facturia-Empresa` con un token de empresa y no coincide
`privilege_escalation`	403	Una llave minteada pedía más scopes o empresas que su minteadora
`email_verification_required`	403	Minteo de una llave `sk_live_` desde una cuenta sin verificar
`test_mode_only`	403	Un endpoint de `/v1/test_helpers` llamado con una llave live

Emisión

Código	HTTP	Causa
`receptor_incomplete`	400	El receptor no está en el registro del SII y no diste `giro`/`address`. `param` nombra el campo
`totals_mismatch`	422	Los `totals` que enviaste como aserción no coinciden con nuestro cálculo. No se emitió nada
`test_field_in_live_mode`	400	El objeto `test` viajó con una llave live
`external_id_exists`	409	Ya existe un documento con ese `external_id` en esta empresa; `error.existing_id` lo nombra
`idempotency_key_reused`	409	Misma `Idempotency-Key`, cuerpo distinto
`idempotency_in_progress`	409	Un request con esa llave sigue en vuelo; reintenta en un momento
`artifact_not_ready`	409	Pediste el XML de un documento que sigue en `queued`
`cedible_not_available`	422	`copy=cedible` en un tipo que no es factura (solo 33 y 34)
`certificate_expired`	422	El certificado de la empresa venció; la empresa está `suspended`
`invalid_field`	400	Un valor de filtro o de enum no reconocido; el mensaje lista los válidos

Recepción

Código	HTTP	Causa
`commercial_response_not_applicable`	422	El tipo de documento no lleva respuesta comercial (solo 33/34/43)
`commercial_response_window_closed`	422	Pasaron los 8 días corridos. `deadline_at` viene en el error
`commercial_response_already_registered`	409	Ya se registró una acción sobre ese documento; es de un solo tiro

Impuestos

Código	HTTP	Causa
`fx_rate_required`	400	`currency` no es `CLP` y no mandaste `fx_rate`
`f29_amount_confirmation_mismatch`	422	`confirm_total_payable` no coincide con la propuesta vigente

Plataforma

Código	HTTP	Causa
`plan_limit_reached`	402	Se agotó una cuota del plan; el cuerpo trae el límite y la URL para subir

Códigos de rechazo del SII

Cuando un documento termina en rejected o reparo, rejection_reasons trae una lista estructurada:

"rejection_reasons": [
  {
    "code": "ted_signature_invalid",
    "sii_code": "TED-2-510",
    "message": "Firma del timbre electrónico incorrecta",
    "hint": "El DD del timbre fue alterado entre la firma y el envío.",
    "retriable": false
  }
]

Código Facturia	Código SII	Causa
`schema_invalid`	`SCH-00001`	Esquema del sobre rechazado
`caratula_invalid`	`RCT`	Datos de la carátula mal (frecuentemente `FchResol` / `NroResol`)
`ted_signature_invalid`	`TED-2-510`	La firma del timbre no coincide
`field_invalid`	`HED-3-211`	Un campo de cabecera lleva un valor que el SII rechaza
`signer_not_authorized`	envío estado 1 / `ESTADO 6`	El certificado firmante no es usuario autorizado de la empresa
`emisor_not_authorized`	`EMP`	Empresa no autorizada a emitir este tipo de documento
`document_not_authorized`	`FNA`	Folio fuera de un CAF autorizado, o CAF revocado
`totals_mismatch`	`DNK`	Los montos enviados difieren de los que calculó el SII

`retriable` es la única señal que importa al reintentar

Un rechazo con retriable: false no cambia de resultado por volver a intentarlo: el documento tiene un problema de datos o de autorización. Un retriable: true sí puede pasar la próxima vez.

No infieras la respuesta del código HTTP: un 502 sii_error puede ser cualquiera de los dos, y la lista de motivos es lo que lo distingue.

La copia legible por máquina

curl https://api.facturia.cl/v1/error_codes

Sin autenticación. Devuelve cada código de Facturia, su contraparte del SII y su retriable, para que tu propio manejo de errores no tenga que transcribir esta tabla a mano.

En esta página