# Codes (/en/docs/errores/codigos) ## API codes [#api-codes] Grouped by where you will run into them. ### Authentication and permissions [#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 [#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 `` 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 `` (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 [#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 [#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 [#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 [#sii-rejection-codes] When a document ends up in `rejected` or `reparo`, `rejection_reasons` carries a structured list: ```json "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 [#the-machine-readable-copy] ```bash curl https://api.facturia.cl/v1/error_codes ``` No 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.