🚦 Códigos de errores xPOS-Core

Aplicable a todos los países

Las fichas por país (Chile, Colombia, …) solo documentan los errores específicos de la entidad tributaria local. Las etapas listadas aquí aplican a todos los países salvo que la descripción de la etapa indique lo contrario.

Fuente

Catalogo mantenido por el equipo de xPOS-Core a partir del runbook interno Códigos de respuestas/errores POS. Se sincroniza contra los stages emitidos por process-documents.

Donde aparece el error en el response

Cuando xPOS-Core no logra completar una operación, el response del protocolo trae estos tres campos poblados:

Campo	Que contiene
message	Operation Error (en caso de error) u Operation Successful (cuando la etapa es 200 — el documento siguio adelante con observación).
stage	El nombre de la etapa que disparo el evento (columna Stage name del catalogo).
error_description	El mensaje humano-legible que describe la causa puntual (columna Mensaje).

El stage es la llave para localizar la fila correcta del catalogo. Cuando un mismo stage puede dispararse por distintos motivos, el error_description discrimina entre filas (caso tipico: MEGAPRINT_RESPONSE_STAGE en Guatemala).

Como leer este catalogo

Stage code (HTTP-like)

El code de cada fila es el status HTTP que recibe el POS en POST /api/v1/process-documents. El servidor lo deriva del stage: TIMEOUT_ERROR_503 → 503, COMPLIANCE_ERROR_510 → 510 y cualquier otro error del procesamiento → 400. El canal WebSocket no tiene status HTTP: devuelve el mismo JSON con su stage.

Los errores que ocurren antes de procesar el documento (JSON mal formado, xPOS bloqueado, hojas de transformación faltantes, certificado vencido) no pasan por este catálogo: ver Status HTTP de la emisión.

Code	Significado
200	Operación completada con observación. El documento siguio su flujo, pero hubo una nota relevante (contingencia, fallback, reintento programado).
400	Error de validación o transformación. xPOS no pudo construir o enviar el documento; requiere acción del POS o del producto. Incluye el documento duplicado (VALIDATE_DUPLICITY_STAGE): la "serie + número" ya existe en la base local de xPOS.
503	Timeout: la entidad tributaria no respondió a tiempo y el documento pudo haber llegado. Solo Colombia, Costa Rica, El Salvador, Guatemala, República Dominicana y Perú.
510	Error de cumplimiento: la entidad tributaria respondió algo que no es una respuesta válida, o recibió el documento y no lo procesó. Solo Colombia y Perú.

Acciones recomendadas

Acción	Que tiene que hacer el POS
Corregir y reintentar	Revisar el input del POS, corregir lo que indica error_description y reenviar.
Reintentar	Reenviar el mismo documento sin cambios — error transitorio o de configuración temporal.
Recargar y reintentar	Pedir al xPOS que vuelva a descargar su configuración (folios, certificados, plantillas) y reenviar. Aplica cuando el problema es de estado local.
Corregir	Revisar el input pero sin reenviar automáticamente (el documento ya fue notificado al backend tributario).
Fin del proceso	No requiere acción del POS — xPOS gestiona el reintento o la condición ya esta resuelta.

Tipo de input

La columna Tipo Input indica los valores de inputType (query param de POST /api/v1/process-documents) que pueden disparar la etapa. Todos significa que aplica a cualquier inputType soportado por el país.

Errores comunes a todos los países

Estas etapas forman parte del pipeline general de xPOS-Core. Se ordenan por la secuencia de ejecución dentro de process-documents.

21 de 21 etapas

Code	Stage name	Motivo	Sugerencia	Acción	Input
400	SET_CONTEXT_STAGE	La petición no trae origin y el equipo tiene más de un emisor instalado.	Enviar el origin con el taxId del emisor dueño de la venta.	Corregir y reintentar	Todos
404	SET_CONTEXT_STAGE	El origin no corresponde a ningún emisor instalado en el equipo.	Revisar el taxId enviado en origin o completar el onboarding de ese emisor.	Corregir y reintentar	Todos
409	SET_CONTEXT_STAGE	Falla interna al resolver el emisor de la petición.	Intentar enviar el documento nuevamente; si persiste, contactar a Gosocket.	Reintentar	Todos
400	TRANSFORM_JSON_STAGE	El proceso de transformacion de JSON a XML <root> fallo (p. ej.: caracteres especiales mal escapados).	Verificar el archivo de origen y corregir; si persiste, contactar a Gosocket.	Corregir y reintentar	json
400	TRANSFORM_ROOT_STAGE	El proceso de transformacion desde XML <root> a XML GUF no se pudo completar.	Recargar la configuracion del xPOS y/o revisar caracteres especiales; si persiste, contactar a Gosocket para revisar el archivo XSLT.	Corregir y reintentar	json, txt, xdoc
400	TRANSFORM_GENERIC_STAGE	El proceso de transformacion desde XML <root> a XML GUF no se pudo completar.	Recargar la configuracion del xPOS y/o revisar caracteres especiales; si persiste, contactar a Gosocket para revisar el archivo XSLT.	Corregir y reintentar	json, txt, xdoc
400	INVALID_REQUEST	La petición no cumple una regla previa del país: en Chile, faltan los datos de resolución (NroResolucion / FechaResolucion) y el nodo CAE; en Perú, la serie de una nota no corresponde al documento que modifica. La validación del typeDoc contra el documento está desactivada.	Corregir el dato que indica error_description y reenviar.	Corregir y reintentar	Todos
400	TRANSFORM_OTHER_STAGE	El proceso de transformacion desde XML <root> a XML GUF no se pudo completar.	Recargar la configuracion del xPOS y/o revisar caracteres especiales; si persiste, contactar a Gosocket para revisar el archivo XSLT.	Corregir y reintentar	txt, xdoc
400	VALIDATE_ISSUER_STAGE	El emisor declarado dentro del documento no coincide con el parametro origin de la peticion (desde la version 2.7.0).	Revisar la configuracion del POS: el origin y el identificador tributario del emisor del documento deben ser el mismo.	Corregir y reintentar	Todos
400	TRANSFORM_FISCAL_STAGE	El proceso de transformacion desde XML GUF a XML fiscal no se pudo completar.	Recargar la configuracion del xPOS y/o revisar caracteres especiales; si persiste, contactar a Gosocket para revisar el archivo XSLT.	Corregir y reintentar	xml
400	VALIDATE_XSD_STAGE	El documento fiscal no paso la validacion de estructura segun el XSD entregado por la entidad tributaria. En El Salvador la validación es contra JSON Schema y la etapa es VALIDATE_JSON_SCHEMA.	Revisar que el documento cumpla con la informacion correcta acorde a los campos observados.	Corregir y reintentar	Todos
400	FOLIATOR_STAGE	xPOS no cuenta con un subrango de numeracion para asignar el folio al documento (requiere GF 3.0 activo). Solo en Colombia, República Dominicana, El Salvador y Perú; en los demás países la falta de folios llega como SERVER_PROCESS_REQUEST_STAGE.	Revisar que el xPOS tenga un subrango descargado o solicitar recarga desde el xPOS; si persiste, contactar a Gosocket.	Reintentar	Todos
400	SIGN_STAGE	xPOS no pudo firmar el documento fiscal (certificado, llave privada o nodo de referencia ausente). Solo en República Dominicana, El Salvador y Perú; en los demás países la falla de firma llega como SERVER_PROCESS_REQUEST_STAGE.	Intentar enviar el documento nuevamente; si persiste, contactar a Gosocket.	Reintentar	Todos
400	VALIDATE_SCHEMATRON_STAGE	El documento fiscal no supero la validacion de contenido Schematron (requiere archivo Schematron cargado).	Revisar que el documento tenga la informacion correcta acorde a los campos observados.	Corregir y reintentar	Todos
400	CUSTOM_RESPONSE_STAGE	No se logro agregar la informacion personalizada en el response (requiere XSLT Customized cargado).	Recargar la configuracion del xPOS; si persiste, contactar a Gosocket para revisar el archivo XSLT.	Reintentar	Todos
400	SERVER_PROCESS_REQUEST_STAGE	Excepcion no controlada al procesar el documento. Incluye la falta de folios, las fallas de firma o certificado, del QR y de escritura en la base local en los países donde esas etapas no tienen un stage propio.	Intentar enviar el documento nuevamente; si persiste, contactar a Gosocket.	Reintentar	Todos
400	REMOVE_PERSONALIZADOS_STAGE	No se logro quitar los campos personalizados antes de emitir el documento fiscal.	Contactar a Gosocket.	Fin del proceso	Todos
200	SEND_DOCUMENT_TO_SAVE	El documento no pudo ser enviado a Gosocket por fallas de conexion.	Ninguna. xPOS reintentara enviar el documento cada 2 minutos.	Fin del proceso	Todos
510	COMPLIANCE_ERROR_510	Solo Colombia y Perú. En Colombia, la DIAN respondió algo que no es una respuesta válida (SOAP Fault o HTML) o falló el envío; en Perú, la entidad tributaria recibió el documento y no lo procesó.	Intentar enviar el documento nuevamente.	Reintentar	Todos
503	TIMEOUT_ERROR_503	La entidad tributaria no respondió a tiempo: el documento pudo haber llegado. Solo Colombia, Costa Rica, El Salvador, Guatemala, República Dominicana y Perú.	Intentar enviar el documento nuevamente; si persiste tras varios intentos, escalar a Gosocket.	Reintentar	Todos
400	VALIDATE_DUPLICITY_STAGE	El documento con la combinacion "serie + numero" ya existe en la base local de xPOS.	Verificar que el documento ya aprobado existe consultando GET /api/v1/status.	Fin del proceso	Todos

Patrones literales de error_description

Algunas etapas devuelven un mensaje con formato estable que el POS puede parsear:

• VALIDATE_DUPLICITY_STAGE: Documento duplicado con el transactionId <UUID>, docNumber <NUM> en la fecha <DD-MM-YYYY HH:mm:ss>. En Perú el mensaje es otro y el error trae la respuesta guardada — ver Perú.
• FOLIATOR_STAGE: No tiene folios activos para el tipo de documento = <N>.

El resto de etapas reenvian el mensaje original de la libreria o de la entidad tributaria, sin formato garantizado.

Errores específicos por país

Cuando la etapa la dispara la entidad tributaria local (o un PAC intermedio), el catalogo agrega filas que solo aplican a ese país.

🇨🇱 Chile (SII)

Code	Stage name	Motivo	Sugerencia	Acción
400	INVALID_REQUEST	Faltan los datos de resolución del emisor (NroResolucion / FechaResolucion) y el documento no trae el nodo CAE.	Completar los datos de resolución en el documento o en el onboarding y reenviar.	Corregir y reintentar

El SII no se contacta durante la petición: el veredicto llega después. Detalle en la ficha de Chile.

🇨🇴 Colombia (DIAN)

Code	Stage name	Motivo	Sugerencia	Acción
400	FIND_SERIE_AND_NUMBER_STAGE_CO	No se pudo completar la busqueda de la serie y folio del documento electrónico.	Revisar que el documento tenga la serie y folio; si persiste, contactar a Gosocket.	Corregir y reintentar
400	FOLIATOR_STAGE	No se pudo asignar el folio: sin folios disponibles o datos de resolución (CAE) incompletos.	Recargar la configuración del xPOS o verificar la asignación de rangos en GF 3.0.	Recargar y reintentar
400	DIAN_RESPONSE_STAGE	La DIAN rechaza o no logro procesar el documento enviado, el certificado está vencido o la Regla 90 es inválida. El error_description reenvia el mensaje de la DIAN.	Revisar el documento, corregir los errores e intentar enviar nuevamente.	Corregir y reintentar
503	TIMEOUT_ERROR_503	La DIAN no respondió en 30 segundos (o respondió HTTP 408).	Reenviar el documento; si persiste tras varios intentos, escalar a Gosocket.	Reintentar
510	COMPLIANCE_ERROR_510	La DIAN respondió algo que no es una respuesta válida —un SOAP Fault o una página HTML, incluso con HTTP 403 o 5xx—, o falló el envío.	Reenviar el documento; si persiste, escalar a Gosocket.	Reintentar

Detalle del flujo DIAN en la ficha de Colombia.

🇬🇹 Guatemala (Megaprint / SAT)

MEGAPRINT_RESPONSE_STAGE se dispara con dos motivos distintos. Para distinguirlos, inspeccionar el campo error_description del response. Los dos responden HTTP 400.

Code	Stage name	Motivo	Sugerencia	Acción
400	MEGAPRINT_RESPONSE_STAGE	Megaprint rechaza el documento o no logro procesarlo. El campo error_description trae el detalle (p. ej.: FEL_GEN102 RESTRICTION_PATTERN).	Revisar error_description, corregir los errores e intentar enviar el documento nuevamente.	Corregir
400	MEGAPRINT_RESPONSE_STAGE (duplicidad)	error_description empieza con Notificacion: Documento enviado anteriormente con el folio XXXXXX-XXXXXXX. Megaprint ya proceso y acepto el documento previamente.	No requiere acción. El POS puede confirmar la aceptación del documento con número XXXXX-XXXXXX.	Fin del proceso
400	ACCESS_NUMBER_GENERATION_STAGE	No esta disponible un subrango de folios de contingencia para asignar al documento.	Revisar si el xPOS tiene descargado un subrango de folios de contingencia. Recargar la configuración del xPOS o verificar la asignación de rangos en GF 3.0.	Recargar y reintentar
400	MEGAPRINT_TOKEN_REQUEST	Megaprint rechazó la solicitud de token (HTTP 4xx) o la respuesta no trae el token y su vigencia. Si el token falla por red, error 5xx o timeout y no hay uno vigente, el documento pasa a contingencia.	Intentar enviar el documento nuevamente para generar un nuevo token.	Reintentar
503	TIMEOUT_ERROR_503	Megaprint no respondió a tiempo al registrar el documento (timeout o HTTP 408/504).	Reenviar el documento; si persiste tras varios intentos, escalar a Gosocket.	Reintentar

Detalle del flujo SAT/Megaprint en la ficha de Guatemala.

🇵🇦 Panama (PAC-GS)

Code	Stage name	Motivo	Sugerencia	Acción
400	PROCESS_PAC_RESPONSE	El PAC rechaza o no logro procesar el documento enviado, o respondió HTTP 4xx. El error_description reenvia el mensaje del PAC.	Revisar el documento, corregir los errores e intentar enviar nuevamente.	Corregir y reintentar

Detalle del flujo PAC-GS en la ficha de Panama.

🇨🇷 Costa Rica (Ministerio de Hacienda)

Code	Stage name	Motivo	Sugerencia	Acción
400	MINISTERIO_HACIENDA_RESPONSE_STAGE	El Ministerio de Hacienda (MH) rechaza o no logro procesar el documento enviado: cualquier respuesta HTTP distinta de 2xx (rechazo, 401, 403, 404…). El error_description reenvia el mensaje del MH.	Revisar el documento, corregir los errores e intentar enviar nuevamente.	Corregir y reintentar
503	TIMEOUT_ERROR_503	Hacienda no respondió a tiempo al pedir el token o al recibir el documento (timeout o HTTP 408/504).	Reenviar el documento; si persiste tras varios intentos, escalar a Gosocket.	Reintentar

Detalle del flujo MH en la ficha de Costa Rica.

🇩🇴 Republica Dominicana (DGII)

Code	Stage name	Motivo	Sugerencia	Acción
400	SEND_RFCE_TO_DGII_STAGE	La DGII rechaza o no logro procesar documentos de tipo RFCE. El error_description reenvia el mensaje de la DGII.	Revisar el documento, corregir los errores e intentar enviar nuevamente.	Corregir y reintentar

| 400 | ET_RESPONSE_STAGE | La DGII rechazó el e-CF o respondió otro error HTTP 4xx (401, 403…). | Revisar el documento o la configuración del emisor según el mensaje y reenviar. | Corregir | | 503 | TIMEOUT_ERROR_503 | La DGII no respondió a tiempo (timeout o HTTP 408/504). Al reenviar el mismo e-NCF, xPOS consulta primero su estado y, si ya es final, responde con ese estado sin reenviarlo. | Reenviar el mismo documento. | Reintentar |

Detalle del flujo DGII en la ficha de Republica Dominicana.

🇸🇻 El Salvador (Ministerio de Hacienda)

Code	Stage name	Motivo	Sugerencia	Acción
400	VALIDATE_JSON_SCHEMA	El documento no cumple el JSON Schema de su tipo (Patrón B).	Revisar el documento según los campos observados, corregir y reenviar.	Corregir y reintentar
400	ET_RESPONSE_STAGE	El Ministerio de Hacienda rechazó el documento.	Revisar el documento, corregir los errores e intentar enviar nuevamente.	Corregir
503	TIMEOUT_ERROR_503	El Ministerio de Hacienda no respondió a tiempo y el documento pudo haber llegado.	Reenviar el documento; si persiste tras varios intentos, escalar a Gosocket.	Reintentar

Detalle del flujo en la ficha de El Salvador.

🇵🇪 Perú (SUNAT / OSE)

Perú no tiene una etapa propia de su entidad tributaria: usa las etapas comunes, y el código HTTP de la respuesta ya indica qué hacer. El error_description lleva siempre el código de SUNAT/OSE adelante (2514 - No existe información de receptor…).

Code	Stage name	Motivo	Sugerencia	Acción
503	TIMEOUT_ERROR_503	No se sabe si llegó: timeout de lectura, corte después de enviar, HTTP 500 sin Fault, 504, Faults 0125, 0140, 0307.	Reenviar ya el mismo documento con el mismo número: si la entidad tributaria ya lo tenía, xPOS recupera la constancia.	Reintentar
510	COMPLIANCE_ERROR_510	La entidad tributaria lo recibió y no lo procesó: error interno, credenciales o configuración, formato o empaquetado (ver la clasificación abajo).	Corregir la causa (o esperar unos minutos si es un error interno de la entidad tributaria) y reenviar con el mismo número: no quedó registrado.	Corregir y reintentar
400	ET_RESPONSE_STAGE	La entidad tributaria lo rechazó: CDR distinto de 0, Faults 2xxx–3xxx, 0100. applicationResponse trae el CDR o el Fault.	Emitir con folio nuevo: el número quedó usado.	Corregir
400	SEND_BILL_STAGE	Error inesperado al preparar o enviar, por ejemplo un destino desconocido en las reglas de ruteo del emisor.	Revisar la configuración del onboarding; escalar a Gosocket.	Corregir
400	VALIDATE_DUPLICITY_STAGE	El número ya tiene una respuesta final (aceptado, en contingencia, rechazado o comprobante físico). El error trae lo guardado: si estaba aceptado, el XML firmado (output) y el CDR (applicationResponse).	No reenviar: usar el XML y el CDR que vienen en el error.	Fin del proceso
400	INVALID_REQUEST	Nota de crédito o débito cuya serie no coincide con el documento que modifica (BC/BD para boletas, FC/FD para facturas).	Corregir la serie de la nota y reenviar.	Corregir y reintentar

Cómo se clasifica el código de SUNAT/OSE. Llega como SOAP Fault o en el CDR, incluso con HTTP 200 del servicio. El código específico manda sobre el rango:

Códigos	Clase	HTTP al POS	Qué hace el POS
0125, 0140, 0307; timeout, HTTP 500 sin Fault, 504	Incierto: no se sabe si llegó	503	Reenviar ya, mismo número
0109, 013x, 020x, 025x	Error interno de la entidad tributaria	510	Esperar unos minutos y reenviar, mismo número
0101–0106, 0110–0113, 0152–0154, 0400; HTTP 401/403	Credenciales o configuración	510	Corregir la configuración y reenviar, mismo número
1xxx, 03xx	Formato	510	Corregir el documento y reenviar, mismo número
0151, 0155–0161, 1034	Empaquetado del envío	510	Escalar a Gosocket; reenviar con el mismo número cuando se resuelva
CDR distinto de 0, 2xxx–3xxx, 0100	Rechazo	400	Emitir con folio nuevo
1032, 1033, 2109 al reenviar	Ya registrado	Según la constancia	xPOS consulta la constancia — ver Reenvío del mismo número
1079 en una boleta o nota de boleta	Se declara por Resumen Diario	200	Nada: el documento pasa a contingencia y se declara en el Resumen Diario

Códigos frecuentes:

Código	Significado	Sugerencia
0100	El sistema no puede responder su solicitud	400: se trata como rechazo aunque no haya CDR. Emitir con folio nuevo.
0102	Usuario o contraseña incorrectos	510: suele indicar credenciales de SUNAT enviadas al OSE (o viceversa). Revisar la configuración de credenciales por proveedor en el portal y reenviar con el mismo número.
0109	El sistema no puede responder su solicitud	510: error interno de la entidad tributaria. Reenviar el mismo documento en unos minutos.
0159 / 0161	El nombre del archivo XML no coincide con el del ZIP	510: problema de armado del envío, no del documento. Escalar a Gosocket.
1033	El comprobante fue registrado previamente	xPOS consulta la constancia: si la entidad tributaria lo tiene aceptado y xPOS tiene el intento previo, responde 200 con el XML original. Sin intento previo es una colisión de numeración (400): emitir con folio nuevo y revisar la asignación de correlativos.
1034	Error de empaquetado del envío	510: escalar a Gosocket. Si el RUC del documento no coincide con el origin, la emisión falla antes, en VALIDATE_ISSUER_STAGE.
2223	El archivo ya fue presentado	Resumen Diario: el lote se rechaza y sus boletas vuelven a la cola para un lote nuevo. No requiere acción.
0126 / 0127	Ticket ajeno o inexistente	Resumen Diario: igual que 2223. No requiere acción.
2335	El documento electrónico ingresado ha sido alterado	400: rechazo de negocio del OSE. Escalar a Gosocket con el transactionId.
2514	No existe información de receptor de documento	400: corregir los datos del receptor y emitir con folio nuevo.
2108, 2329, 2600, 2950	Fuera de plazo	Rechazo por plazo de un documento en contingencia: estado 3 en el Inbox, nota «PLAZO» y registro en «Documentos erróneos». Sin respuesta formal de la entidad tributaria, xPOS usa el código XPOS_PLAZO_VENCIDO. Ver Plazos.

Detalle del flujo SUNAT/OSE en la ficha de Perú.

Guia rápida de resolución

Cuando llega un response con message: "Operation Error":

1. Leer stage → ubicar la fila en este catalogo.
2. Leer error_description → distinguir entre filas que comparten stage (caso Guatemala).
3. Aplicar la acción:
   • Corregir y reintentar → corregir input y volver a llamar POST /api/v1/process-documents.
   • Reintentar → reenviar tal cual.
   • Recargar y reintentar → llamar PUT /api/v1/reobtain-config y reenviar.
   • Fin del proceso → no reenviar; el documento esta resuelto (duplicado, reintento automático programado, o requiere escalamiento manual a Gosocket).
4. Si stage no esta en este catalogo → revisar logs operativos con GET /api/v1/db-data/logs/search?uuid=<transactionId> y escalar a Gosocket.