Errors and status codes

Every failure the SDK raises on purpose is a DteError with a stable code. You branch on the code and read the context from details; you never parse the message. This page lists every code, what raises it and what its details usually hold, then covers the SII status codes (upload, reception, document, claims and transferability) that are returned as data rather than thrown.

Using DteError#

import { createDocument, DteError, errorCode, isDteError } from 'dte-sdk'
 
try {
  createDocument({ ...input, items: [{ name: 'x'.repeat(81), unitPrice: 1 }] })
} catch (error) {
  if (isDteError(error)) {
    error.code // 'FIELD_TOO_LONG'
    error.message // 'Field exceeds the maximum length allowed by the SII schema (field=NmbItem, maxLength=80, length=81)'
    error.details // { field: 'NmbItem', maxLength: 80, length: 81, value: 'xxxxxxxx…' }
  }
}

details versus message#

The message is generic and safe to log: it is a fixed sentence per code, followed by a short list of safe detail keys, that is, field names, codes and numbers. It never includes RUTs, names, item text, URLs or response bodies. The safe keys are field, maxLength, length, type, folio, from, to, kind, index, status, httpStatus, code, attempts, channel, operation, trackId, expected, actual, rejection, step, module, day, listed and covered.

Everything else lives in details only: the offending value, a RUT, a response excerpt (with tokens and seeds redacted), the URL that was called. Treat details as sensitive: do not send it whole to a log or to an error tracker. Pick the keys you need (error.details.field, error.details.status).

logger.error('upload failed', { code: error.code, status: error.details.status }) // fine
logger.error('upload failed', error.details) // may carry RUTs, a response excerpt, the offending value

Error codes#

Codes are grouped by what they are about. "Typical details" are the keys the code usually carries; an operation may add more (every transport error also carries operation).

Input validation#

CAF and folios#

Certificate#

XML and signatures#

Transport#

When a transport failure happens after the response headers arrived (while the body was being read), details.responseStarted is true: the SII did answer, at least in part.

SII web services#

Portal#

Optional dependencies#

Retrying#

isRetryableError(error) is true for:

It is false for everything else, including TRANSPORT_TLS (a misconfigured trust store does not fix itself) and SII_TOKEN_INVALID (the client already renews the token once). The SII client uses it as the default of retry.retryOn, with exponential backoff and six attempts. Two things to remember:

• An upload or a claim is not retried just because the error is retryable. Those calls change state at the SII and are sent again only while no answer has arrived. SII_UPLOAD_REJECTED with status 9 is "retryable" by this function, but an upload that got that answer is never re-sent automatically: you decide. See the retry policy.
• The portal has its own rule, isRetryablePortalError from dte-sdk/portal: transport failures, timeouts, HTTP 502, 503 and 504, and the intermittent TLS failures that the SII produces with a client certificate (EPROTO). A session limit, a block or a rejection is never repeated, because repeating makes them worse. Its policy, DEFAULT_PORTAL_RETRY_POLICY, is 4 attempts at 2, 4 and 8 seconds, without jitter.

Portal rejections#

A SII_PORTAL_REJECTED is the portal refusing a request on business grounds: the company is not enrolled, the quota is exhausted, the backup is blocked. details.rejection is a PortalRejection code. portalRejectionMessage(rejection) and the PORTAL_REJECTIONS map, both from dte-sdk/portal, give the full explanation in Spanish, written for the operator, with what to do about it.

import { isDteError } from 'dte-sdk'
import { portalRejectionMessage, requestCaf, type PortalRejection } from 'dte-sdk/portal'
 
try {
  await requestCaf(portal, { type: 33, quantity: 50 })
} catch (error) {
  if (isDteError(error) && error.code === 'SII_PORTAL_REJECTED') {
    console.error(portalRejectionMessage(error.details.rejection as PortalRejection))
    console.error(error.details.portalMessage) // what the portal said, when it said something
  } else {
    throw error
  }
}

The codes, by area:

See Portal and Register for the functions behind them.

Status codes#

The SII reports outcomes with short codes. The SDK returns them as data (they are not exceptions), classifies them and gives their Spanish gloss. The glosses are in Spanish because they are the SII's own vocabulary.

import {
  classifyDocumentStatus,
  classifyUploadStatus,
  documentStatusMessage,
  isRetryableStatus,
  isTokenErrorStatus,
  uploadStatusMessage,
} from 'dte-sdk'
 
classifyUploadStatus('EPR') // 'accepted'
classifyUploadStatus('RCT') // 'rejected'
classifyUploadStatus('-11') // 'queryError': retry
classifyUploadStatus('RLV') // 'rejected' on SOAP…
classifyUploadStatus('RLV', 'rest') // …and 'accepted' on the receipts REST API
classifyUploadStatus('XYZ') // 'unknown'
classifyDocumentStatus('FAU') // 'notReceived'
 
uploadStatusMessage('EPR') // 'Envío procesado'
documentStatusMessage('FAU') // 'DTE no recibido por el SII'
isRetryableStatus('-11') // true
isTokenErrorStatus('-3') // true: renew the token and try once more

Upload statuses#

The ESTADO of QueryEstUp (or the REST estado) of an envelope or a book. classifyUploadStatus(code, channel = 'soap') returns one of these classes; uploadStatusMessage(code, channel) the gloss, or Estado desconocido: <code>.

isRetryableStatus(code) is true for the queryError class. isTokenErrorStatus(code) is true for -3, -13, 001, 002 and 003: the client renews the token once when it sees one.

Reception statuses#

The STATUS of the RECEPCIONDTE answer that DTEUpload gives when it takes (or refuses) a file. RECEPTION_STATUS is the catalog, classifyReceptionStatus(code) the class and receptionStatusMessage(code) the gloss. SII_UPLOAD_REJECTED.details.status is this code as a number.

Document statuses#

The ESTADO of QueryEstDte (or the REST codigo) of one document. classifyDocumentStatus(code) and documentStatusMessage(code); any negative code is a queryError, anything else unlisted is unknown.

Claim and transferability codes#

The registry answers with a codResp number. claimResponseMessage(code) gives the gloss (Código de respuesta desconocido: <code> for a code not listed), and CLAIM_RESPONSE_CODES is the catalog.

queryTransferable answers with codes 20 to 25. transferabilityMessage(code) gives the gloss, and TRANSFERABILITY_CODES the catalog, with what each implies:

The events that listClaimEvents reports (CLAIM_EVENT_CODES): ACD (acepta contenido), RCD (reclamo al contenido), ERM (otorga recibo de mercaderías o servicios), RFP (reclamo por falta parcial), RFT (reclamo por falta total), NCA (nota de crédito de anulación), ENC (otra nota de crédito) and PAG (DTE pagado al contado, which the SII registers itself).

Code 27 is the registry refusing an event on a document paid in cash or free: production answered it on 11 November 2026 to an acceptance of an invoice whose events listed PAG alone. receiverAnswer reads such a document as paidInCash, so there is nothing to send (see receiverAnswer). Before 0.8.0 the catalog did not know it, and claimResponseMessage(27) gave Código de respuesta desconocido: 27.

Next steps#

• SII web services shows where these errors and statuses come from, and how retries and token renewal work.
• Portal explains the session, the limits and the refusals of the portal.
• Security says what to keep out of your logs.