Errores y códigos de estado

Toda falla que el SDK lanza a propósito es un DteError con un code estable. Tú decides según el código y lees el contexto desde details; nunca interpretas el mensaje. Esta página lista cada código, qué lo lanza y qué suelen traer sus details, y luego cubre los códigos de estado del SII (envío, recepción, documento, reclamos y cedibilidad), que se devuelven como dato y no se lanzan.

Usar 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 frente a message#

El mensaje es genérico y seguro de registrar: es una frase fija por código, seguida de una lista corta de claves de detalle seguras, es decir, nombres de campo, códigos y números. Nunca incluye RUT, nombres, texto de ítems, URL ni cuerpos de respuesta. Las claves seguras son field, maxLength, length, type, folio, from, to, kind, index, status, httpStatus, code, attempts, channel, operation, trackId, expected, actual, rejection, step, module, day, listed y covered.

Todo lo demás vive solo en details: el valor ofensivo, un RUT, un extracto de respuesta (con tokens y semillas tachados), la URL que se llamó. Trata details como sensible: no lo envíes completo a un log ni a un rastreador de errores. Elige las claves que necesitas (error.details.field, error.details.status).

logger.error('upload failed', { code: error.code, status: error.details.status }) // bien
logger.error('upload failed', error.details) // puede traer RUT, un extracto de respuesta, el valor ofensivo

Códigos de error#

Los códigos están agrupados por tema. Los "details típicos" son las claves que el código suele traer; una operación puede agregar más (todo error de transporte trae además operation).

Validación de entradas#

CAF y folios#

Certificado#

XML y firmas#

Transporte#

Cuando una falla de transporte ocurre después de que llegaron las cabeceras de la respuesta (mientras se leía el cuerpo), details.responseStarted es true: el SII sí respondió, al menos en parte.

Servicios web del SII#

Portal#

Dependencias opcionales#

Reintentos#

isRetryableError(error) es true para:

Es false para todo lo demás, incluidos TRANSPORT_TLS (un almacén de confianza mal configurado no se arregla solo) y SII_TOKEN_INVALID (el cliente ya renueva el token una vez). El cliente del SII la usa como valor por defecto de retry.retryOn, con backoff exponencial y seis intentos. Dos cosas que recordar:

• Un envío o un reclamo no se reintenta solo porque el error sea reintentable. Esas llamadas cambian estado en el SII y se reenvían únicamente mientras no haya llegado respuesta. SII_UPLOAD_REJECTED con estado 9 es "reintentable" según esta función, pero un envío que recibió esa respuesta nunca se reenvía automáticamente: lo decides tú. Ver la política de reintentos.
• El portal tiene su propia regla, isRetryablePortalError de dte-sdk/portal: fallas de transporte, timeouts, HTTP 502, 503 y 504, y las fallas TLS intermitentes que el SII produce con un certificado cliente (EPROTO). Un límite de sesiones, un bloqueo o un rechazo nunca se repite, porque repetir los empeora. Su política, DEFAULT_PORTAL_RETRY_POLICY, es de 4 intentos a los 2, 4 y 8 segundos, sin jitter.

Rechazos del portal#

Un SII_PORTAL_REJECTED es el portal rechazando una solicitud por motivos de negocio: la empresa no está inscrita, se agotó el cupo, el respaldo está bloqueado. details.rejection es un código PortalRejection. portalRejectionMessage(rejection) y el mapa PORTAL_REJECTIONS, ambos de dte-sdk/portal, entregan la explicación completa en español, escrita para el operador, con qué hacer al respecto.

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) // lo que dijo el portal, cuando dijo algo
  } else {
    throw error
  }
}

Los códigos, por área:

Ver Portal y Registro para las funciones que hay detrás.

Códigos de estado#

El SII informa los resultados con códigos cortos. El SDK los devuelve como dato (no son excepciones), los clasifica y entrega su glosa en español. Las glosas están en español porque son el vocabulario propio del SII.

import {
  classifyDocumentStatus,
  classifyUploadStatus,
  documentStatusMessage,
  isRetryableStatus,
  isTokenErrorStatus,
  uploadStatusMessage,
} from 'dte-sdk'
 
classifyUploadStatus('EPR') // 'accepted'
classifyUploadStatus('RCT') // 'rejected'
classifyUploadStatus('-11') // 'queryError': reintentar
classifyUploadStatus('RLV') // 'rejected' en SOAP…
classifyUploadStatus('RLV', 'rest') // …y 'accepted' en la API REST de boletas
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: renueva el token y prueba una vez más

Estados de envío#

El ESTADO de QueryEstUp (o el estado REST) de un sobre o un libro. classifyUploadStatus(code, channel = 'soap') devuelve una de estas clases; uploadStatusMessage(code, channel) la glosa, o Estado desconocido: <code>.

isRetryableStatus(code) es true para la clase queryError. isTokenErrorStatus(code) es true para -3, -13, 001, 002 y 003: el cliente renueva el token una vez cuando ve uno.

Estados de recepción#

El STATUS de la respuesta RECEPCIONDTE que entrega DTEUpload cuando recibe (o rechaza) un archivo. RECEPTION_STATUS es el catálogo, classifyReceptionStatus(code) la clase y receptionStatusMessage(code) la glosa. SII_UPLOAD_REJECTED.details.status es este código como número.

Estados de documento#

El ESTADO de QueryEstDte (o el codigo REST) de un documento. classifyDocumentStatus(code) y documentStatusMessage(code); cualquier código negativo es queryError, y cualquier otro no listado es unknown.

Códigos de reclamo y de cedibilidad#

El registro responde con un número codResp. claimResponseMessage(code) entrega la glosa (Código de respuesta desconocido: <code> para un código no listado), y CLAIM_RESPONSE_CODES es el catálogo.

queryTransferable responde con los códigos 20 a 25. transferabilityMessage(code) entrega la glosa, y TRANSFERABILITY_CODES el catálogo, con lo que implica cada uno:

Los eventos que informa listClaimEvents (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) y PAG (DTE pagado al contado, que registra el propio SII).

El código 27 es el registro rechazando un evento sobre un documento pagado al contado o gratuito: producción lo respondió el 11 de noviembre de 2026 a la aceptación de una factura cuyos eventos listaban solo PAG. receiverAnswer lee un documento así como paidInCash, así que no hay nada que enviar (revisa receiverAnswer). Antes de la 0.8.0 el catálogo no lo conocía, y claimResponseMessage(27) daba Código de respuesta desconocido: 27.

Próximos pasos#

• Servicios web del SII muestra de dónde vienen estos errores y estados, y cómo funcionan los reintentos y la renovación de token.
• Portal explica la sesión, los límites y los rechazos del portal.
• Seguridad dice qué mantener fuera de tus logs.