Catálogo de errores

Todos los errores Notta siguen el shape { code, message, request_id, hint?, next_action?, detail?, docs_url? }. El campo next_action es enumerable y está diseñado para que un agente LLM pueda razonar qué hacer sin necesidad de leer el message.

Estructura

type ErrorResponse = {
  code: string;          // "nc.over_cedida.blocked"
  message: string;       // human-readable
  request_id: string;    // siempre presente — UUID por request
  hint?: string;         // fix sugerido
  next_action?: string;  // enum estable: "confirm_override_and_retry" | "retry_with_backoff" | ...
  detail?: Record<string, unknown>; // campos públicos del error, p. ej. { "retryAfterSec": 30 }
  docs_url?: string;     // link a la doc del error, cuando aplica
  issues?: unknown[];    // solo en validation_failed — issues Zod con path + message por campo
};

Incluye el request_id al contactar soporte: es el identificador que correlaciona tu request con los logs del servidor.

Códigos por dominio

Cuando un código no trae next_action (marcado con —), la corrección sale del code más el detail.

Autenticación y permisos

Validación del payload

Lectura y estado del DTE

Muestras impresas (certificación)

Certificado y folios (CAF) en la emisión

Gestión de certificados (/certificates)

Gestión de CAF (/caf)

Notas de crédito y débito (compliance)

Guía de despacho (52)

SII y errores transitorios

Boletas

BHE

Billing

Infraestructura (transitorios del servidor)

Reintenta con backoff; si persisten, contacta soporte con el request_id.

RCV y RCOF

Ejemplo: factura cedida

{
  "code": "nc.over_cedida.blocked",
  "message": "NC inoponible al cesionario: la factura referenciada (folio 1234) tiene una cesión RPETC aceptada irrevocablemente (Doctrina Corte Suprema 2025).",
  "hint": "Factura cedida via RPETC con cesión irrevocable (≥8d). Set override_cedida=true en el body con respaldo operacional firmado.",
  "next_action": "confirm_override_and_retry",
  "detail": { "folioRef": 1234 },
  "request_id": "9f3b2c61-7d4a-4e0b-9c2d-1a5e8f3b7c90"
}

Rechazos del SII (al subir el DTE)

Cuando el SII recibe el EnvioDTE corre una cascada de validadores: XSD → schema → firma → carátula → timbre. Cada validador enmascara al siguiente, así que corregir un rechazo suele destapar el próximo en ese mismo orden.

El getEstUp del SII devuelve solo el código de cabecera (RFR/RCT/EPR); el sub-código accionable (p. ej. CRT-3-19, TED-2-510) llega por email del SII. Notta lo expone en sii_glosa.

RFR — Rechazado por Error en Firma

La firma se rompió porque los bytes canónicos que el SII verifica no son los que se firmaron: un xmlns heredado que el c14n omite al firmar e incluye al verificar, o un XML re-serializado después de firmar.

Cómo verificarlo: ejecuta un roundtrip local de firma + verificación sobre los bytes exactos que van al wire. Si el elemento firmado (SetDTE/Documento) solo hereda el namespace sin declararlo, el self-verify falla — redeclara xmlns explícito y firma con c14n-20010315 (el c14n exclusivo lo rechaza el XSD del SII).

CHR-00002 — línea muy larga o charset inválido

El validador de charset cortó el envío porque alguna línea del XML supera los 4090 caracteres o los bytes no van en ISO-8859-1.

Cómo verificarlo: mide el largo de línea máximo del XML enviado y confirma que el wire va como latin1, con saltos de línea entre las secciones mayores (Encabezado, Detalle, TED).

RCT — Rechazado por Error en Carátula

La carátula declara datos que el SII no tiene registrados para el emisor: RutEmisor/RutEnvia que no corresponden, o una resolución (FchResol/NroResol) inválida.

Cómo verificarlo: el sub-código del email del SII apunta al campo exacto (p. ej. CRT-3-19 es la resolución). Compara cada campo de la carátula contra lo registrado para la empresa en el SII antes de reenviar.

CRT-3-19 — Fecha/Número de Resolución inválido

La FchResol no es la fecha que el SII tiene registrada para tu empresa: en certificación el comodín 2014-08-22 no sirve para empresas recién postuladas — el SII espera la fecha real de postulación.

Cómo verificarlo: reenvía con FchResol = fecha en que la empresa postuló como emisor electrónico en maullin y NroResol = 0 (válido para todo emisor en certificación). Si el envío pasa, el comodín era el problema.

TED-2-510 — firma del timbre incorrecta

La firma FRMT se calculó sobre los bytes literales del DD, pero el SII la verifica sobre el DD canónico con el whitespace entre elementos colapsado.

Cómo verificarlo: verifica la FRMT localmente contra la clave pública del CAF usando dd.replace(/>\s+</g, "><") como input. Si verifica con la forma canónica y falla con la literal, re-firma el timbre sobre la canónica (preservando los bytes literales del CAF en el wire).

Cómo manejar errores en código

const res = await fetch("https://app.notta.cl/api/v1/dtes", { /* ... */ });
if (!res.ok) {
  const err = await res.json();
  switch (err.next_action) {
    case "retry_with_backoff": return retryLater(err.detail?.retryAfterSec);
    case "regenerate_api_key": return notifyOps(err);
    case "confirm_override_and_retry": return promptUser(err);
    default: throw new Error(`${err.code} (request_id: ${err.request_id})`);
  }
}

Buenas prácticas

• Decide por error.code (y next_action cuando viene), nunca por string-matching del message: el texto puede cambiar, los códigos no.
• next_action es enumerable y estable — los valores existentes no cambian de semántica; solo se agregan nuevos.
• No reintentes los 4xx salvo 429: un 400/422 va a fallar igual hasta que corrijas el payload. Los 502/503 transitorios sí se reintentan con backoff.
• Loguea el request_id de cada error en tu sistema: acelera cualquier diagnóstico con soporte.

Próximos pasos

• Límites de tasa — el detalle del 429 y el patrón de backoff para errores transitorios.
• Referencia API de DTEs — los endpoints que emiten estos códigos.
• Nota de crédito (61) — el flujo completo detrás de nc.over_cedida.blocked y el plazo de 6 meses.
• Webhooks — el contrato de eventos para reaccionar a rechazos sin polling.