Errors
Codes
The error codes the API returns and the SII's rejection codes, with their cause and whether retrying is worth it.
API codes
Grouped by where you will run into them.
Authentication and permissions
| Code | HTTP | Cause |
|---|---|---|
insufficient_scope | 403 | The key is missing a scope; error.message names which one |
empresa_required | 400 | The Facturia-Empresa header is missing on an empresa-scoped call |
empresa_not_allowed | 403 | The empresa is outside the key's allowlist |
empresa_mismatch | 400 | You sent Facturia-Empresa with an empresa-bound token and it does not match |
privilege_escalation | 403 | A minted key asked for more scopes or empresas than the key that minted it |
api_key_roll_conflict | 409 | Two simultaneous rolls of the same key; the other one won and its secret is the live one |
email_verification_required | 403 | Minting an sk_live_ key from an unverified account |
test_mode_only | 403 | A /v1/test_helpers endpoint called with a live key |
Emission
| Code | HTTP | Cause |
|---|---|---|
receptor_incomplete | 400 | The receptor is missing giro/address and no earlier document of this company to the same RUT supplies them. param names the field |
totals_mismatch | 422 | The totals you sent as an assertion do not match our computation. Nothing was issued |
test_field_in_live_mode | 400 | The test object traveled with a live key |
external_id_exists | 409 | A document with that external_id already exists in this empresa; error.existing_id names it |
idempotency_key_reused | 409 | Same Idempotency-Key, different body |
idempotency_in_progress | 409 | A request with that key is still in flight; retry in a moment |
artifact_not_ready | 409 | You asked for the XML of a document still in queued |
artifact_not_available | 409 | The document was issued directly in the SII portal (SFG); its XML was never in Facturia's custody and is only recoverable through the portal's manual "Respaldo de DTE y/o IECV" download |
cedible_not_available | 422 | copy=cedible on a type that is not a factura, Chile's invoice (only 33 and 34) |
cedible_not_available_for_channel | 422 | copy=cedible on a document with emission_channel=sfg; the SII signs and stamps its own PDF, with no cedible variant |
cesion_not_applicable | 422 | You asked whether a type is cedible (assignable to a factor) when it is not: the SII registry only answers for 33, 34 and 43 |
cesion_status_not_available | 409 | You asked for the cedible status of a document the SII has not registered yet (queued, sent) or never will (failed, rejected) |
certificate_expired | 422 | The empresa's certificate expired; the empresa is suspended |
caf_belongs_to_another_empresa | 422 | The <RE> of the CAF (the SII-signed block of folios — the pre-authorized numbers a document must carry) you uploaded to POST /cafs names a different RUT (taxpayer id). The SII issues a CAF to a single issuer: any document drawn from another empresa's range is rejected, and by then the folio is already spent |
caf_expired | 422 | The folio range ran out of vigencia: a CAF is valid for six calendar months from its <FA> (Res. Ex. SII N° 58 of 2017), and the SII rejects on reception any document drawn from an expired one. The emission is refused before a folio is spent. Request new folios, then annul the unused ones of the expired range |
tipo_not_available_for_channel | 422 | The empresa's channel does not issue that type: sfg issues 33/34/52/56/61 and refuses only the 46 (the SII portal itself will not open the form without agente retenedor — withholding agent — authorization); mercado issues every published type. Boletas 39/41 do not reach this code: they leave through Facturia's own engine whatever the channel says, and what gates them is the SII's boleta habilitación — an empresa without it gets empresa_not_emitting naming the habilitacion step |
dispatch_required | 400 | A guía de despacho, the dispatch note (52), with no dispatch block |
dispatch_incomplete | 422 | The dispatch block carries no transfer_type (the IndTraslado), which defines whether the guía constitutes a sale |
dispatch_not_applicable | 422 | You sent dispatch.transfer_type (IndTraslado) or dispatch.dispatch_type (TipoDespacho) on a type that is not a guía |
dispatch_not_available_for_channel | 422 | dispatch.destination or dispatch.dispatch_type on an sfg empresa: the portal's form carries a single address — the receptor's — and has no TipoDespacho field. On mercado both are accepted |
sfg_guia_zero_amount | 422 | A guía (52) with a line at unit_price 0 or a total of 0 on an sfg empresa: the portal validates the guía with the factura's validations and demands a price above 0 for every class of transfer. On mercado a zero amount is accepted |
line_discount_not_available_for_channel | 422 | items[].discount_percent above 0 on an sfg empresa: the portal's form has no per-line discount field in any capture of ours, so accepting it would quote you a discounted total and issue the document without it. Fold the discount into unit_price, or issue via emission_channel=mercado |
global_discount_not_available_for_channel | 422 | global_discounts on an sfg empresa: the portal's form has its discount inputs commented out, there is nowhere to put it. Same remedy as the per-line one |
invalid_field | 400 | An unrecognized filter or enum value; the message lists the valid ones |
field_too_long | 400 | A field exceeds the maxLength the SII's XSD puts on the element it turns into (receptor.giro → GiroRecep 40, receptor.legal_name → RznSocRecep 100, receptor.address.street → DirRecep 70, dispatch.carrier.plate → Patente 8, …). It is rejected, never truncated |
Reception
| Code | HTTP | Cause |
|---|---|---|
commercial_response_not_applicable | 422 | The document type carries no commercial response (only 33/34/43) |
commercial_response_window_closed | 422 | The 8 calendar days elapsed. deadline_at comes in the error |
commercial_response_already_registered | 409 | An action was already registered on that document; it is one-shot |
Taxes
| Code | HTTP | Cause |
|---|---|---|
fx_rate_required | 400 | currency is not CLP and you did not send fx_rate |
f29_amount_confirmation_mismatch | 422 | confirm_total_payable does not match the current proposal |
Platform
| Code | HTTP | Cause |
|---|---|---|
plan_limit_reached | 402 | Declared and never raised: the plan is flat and documents are unlimited, so nothing returns this code today. It is published so a client that already handles a 402 has something to program against |
subscription_required | 402 | That empresa has no active subscription and the act is a real one (emission, credit note, folios, sending, going live). Billing is per empresa: the others carry on |
payload_too_large | 413 | The body exceeds the surface's cap (2 MB for JSON, 9 MB for multipart/form-data). The message names the cap in bytes. It is answered before the key is checked, so it can arrive unauthenticated; nothing was read and nothing was stored. If you are hitting it with JSON, it is almost always a file sent as base64: the upload endpoints take multipart/form-data |
SII rejection codes
When a document ends up in rejected or reparo, rejection_reasons carries a structured list:
"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
}
]| Facturia code | SII code | Cause |
|---|---|---|
schema_invalid | SCH-00001 | The envelope's schema was rejected |
caratula_invalid | RCT | Bad data in the carátula, the envelope's cover block (often FchResol / NroResol) |
ted_signature_invalid | TED-2-510 | The electronic stamp's signature does not match |
field_invalid | HED-3-211 | A header field carries a value the SII rejects |
signer_not_authorized | submission status 1 / ESTADO 6 | The signing certificate is not an authorized user of the empresa |
emisor_not_authorized | EMP | Empresa not authorized to issue this document type |
document_not_authorized | FNA | Folio outside an authorized CAF, or a revoked CAF |
totals_mismatch | DNK | The amounts sent differ from the ones the SII computed |
`retriable` is the only signal that matters when retrying
A rejection with retriable: false does not change outcome just because you try again: the document
has a data or an authorization problem. A retriable: true one can go through next time.
Do not infer the answer from the HTTP status: a 502 sii_error can be either of the two, and the
list of reasons is what tells them apart.
The machine-readable copy
curl https://api.facturia.cl/v1/error_codesNo authentication. It returns every Facturia code, its SII counterpart and its retriable, so your
own error handling does not have to transcribe this table by hand.