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 fila de ESTE código en el catálogo de abajo
  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.

Toda respuesta de la API lleva además ese mismo identificador en el header X-Request-Id, no solo las de error: también los 200, y también las que no son JSON (/dtes/{id}/xml, /pdf, /muestras). Si necesitas reportar una respuesta exitosa que te parece incorrecta —una lectura que devolvió de menos, un listado que no cuadra— ese header es lo que nos deja encontrar tu request exacto y con qué parámetros salió. Guárdalo también en el camino feliz.

docs_url apunta a la fila exacta de tu código en el catálogo de abajo (p. ej. https://notta.cl/docs/errors#e-caf.not_found). Viene en todo error cuyo código esté documentado aquí; si un error no lo trae, es que su código todavía no tiene fila — nunca un link roto.

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)

Situación tributaria de la organización y solicitud de acceso

Estos códigos no vienen de un documento: vienen del RUT de la organización, o de quién puede operarla. Ninguno se arregla reintentando.

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

Guía de despacho (52)

SII y errores transitorios

Recepción de compras — acuses y reclamos (/recepcion)

Registrar un acuse o un reclamo va ante el SII por SOAP y le avisa a tu proveedor: sus rechazos son del SII, no de Notta.

Conexiones MCP: topes por minuto

Sólo los reciben las conexiones MCP; una API key no pasa por estos topes. El tope lo fija cada empresa en /app/mcp ("Tope de acciones por minuto") y cada tipo de acción tiene su propio cupo, así que previsualizar no te deja sin emitir. Las respuestas exitosas traen RateLimit-Remaining: no hace falta chocar el tope para conocerlo.

Boletas

BHE

Billing

Infraestructura (transitorios del servidor)

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

RCV

Sucursales del SII (/sucursales)

Webhooks salientes (/webhooks)

Los demás códigos de /webhooks son los comunes: idempotency_key_missing y invalid_json (400), unauthorized (401), forbidden si a la API key le falta webhook:read o webhook:write (403), validation_failed si la url o los events no cumplen el schema (422), y not_found si el id no existe, es de otra empresa o es del otro ambiente (404).

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 respuesta en tu sistema —del header X-Request-Id, que viene también en los 200—: acelera cualquier diagnóstico con soporte, y es lo único que permite investigar una respuesta exitosa pero sospechosa.

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 push firmado que te avisa de un rechazo sin que preguntes.