🚦 Codigos de errores xPOS-Core

Aplicable a todos los paises

Las fichas por pais (Chile, Colombia, …) solo documentan los errores especificos de la entidad tributaria local. Las etapas listadas aqui aplican a todos los paises salvo que se indique lo contrario en la columna "Pais".

Fuente

Catalogo mantenido por el equipo de xPOS-Core a partir del runbook interno Codigos 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 operacion, 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 observacion).
stage	El nombre de la etapa que disparo el evento (columna Stage name del catalogo).
errorDescription	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 errorDescription discrimina entre filas (caso tipico: MEGAPRINT_RESPONSE_STAGE en Guatemala).

Como leer este catalogo

Stage code (HTTP-like)

xPOS-Core usa cinco codigos para clasificar el evento. No se mapean 1:1 al HTTP devuelto por la API REST: son una etiqueta operativa interna.

Code	Significado
200	Operacion completada con observacion. El documento siguio su flujo, pero hubo una nota relevante (contingencia, fallback, reintento programado).
400	Error de validacion o transformacion. xPOS no pudo construir o enviar el documento; requiere accion del POS o del producto.
404	Documento duplicado: la "serie + numero" ya existe en la base local de xPOS.
503	Timeout: la entidad tributaria tardo mas de 30 segundos en responder.
510	Error de cumplimiento: excepcion al enviar a la entidad tributaria (red, autenticacion, formato rechazado).

Acciones recomendadas

Accion	Que tiene que hacer el POS
Corregir y reintentar	Revisar el input del POS, corregir lo que indica errorDescription y reenviar.
Reintentar	Reenviar el mismo documento sin cambios — error transitorio o de configuracion temporal.
Recargar y reintentar	Pedir al xPOS que vuelva a descargar su configuracion (folios, certificados, plantillas) y reenviar. Aplica cuando el problema es de estado local.
Corregir	Revisar el input pero sin reenviar automaticamente (el documento ya fue notificado al backend tributario).
Fin del proceso	No requiere accion del POS — xPOS gestiona el reintento o la condicion 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 pais.

Errores comunes a todos los paises

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

17 de 17 etapas

Code	Stage name	Motivo	Sugerencia	Acción	Input
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	El valor del query param typeDoc no coincide con el tipo del documento dentro del DTE, o el typeDoc no esta declarado en el onboarding.	Corregir el typeDoc del request o el tipo de documento dentro del DTE.	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	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 o JSON Schema entregado por la entidad tributaria.	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).	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).	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 transformar el input en documento fiscal.	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	Excepcion al enviar el documento a la entidad tributaria (red, autenticacion, formato rechazado).	Intentar enviar el documento nuevamente.	Reintentar	Todos
503	TIMEOUT_ERROR_503	El tiempo de respuesta de la entidad tributaria supero los 30 segundos.	Intentar enviar el documento nuevamente; si persiste tras varios intentos, escalar a Gosocket.	Reintentar	Todos
404	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 errorDescription

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>.
• FOLIATOR_STAGE: No tiene folios activos para el tipo de documento = <N>.
• INVALID_REQUEST: [VALIDATE TYPE DOC] typeDoc <N> ....

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

Errores especificos por pais

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

🇨🇴 Colombia (DIAN)

Code	Stage name	Motivo	Sugerencia	Accion
400	FIND_SERIE_AND_NUMBER_STAGE_CO	No se pudo completar la busqueda de la serie y folio del documento electronico.	Revisar que el documento tenga la serie y folio; si persiste, contactar a Gosocket.	Corregir y reintentar
400	DIAN_RESPONSE_STAGE	La DIAN rechaza o no logro procesar el documento enviado. El errorDescription reenvia el mensaje de la DIAN.	Revisar el documento, corregir los errores e intentar enviar nuevamente.	Corregir y 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.

Code	Stage name	Motivo	Sugerencia	Accion
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 accion. El POS puede confirmar la aceptacion del documento con numero XXXXX-XXXXXX.	Fin del proceso
200	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 configuracion del xPOS o verificar la asignacion de rangos en GF 3.0.	Recargar y reintentar
200	MEGAPRINT_TOKEN_REQUEST	Problemas con el token asignado al xPOS.	Intentar enviar el documento nuevamente para generar un nuevo token.	Reintentar

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

🇵🇦 Panama (PAC-GS)

Code	Stage name	Motivo	Sugerencia	Accion
200	PROCESS_PAC_RESPONSE	El PAC rechaza o no logro procesar el documento enviado. El errorDescription 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	Accion
400	MINISTERIO_HACIENDA_RESPONSE_STAGE	El Ministerio de Hacienda (MH) rechaza o no logro procesar el documento enviado. El errorDescription reenvia el mensaje del MH.	Revisar el documento, corregir los errores e intentar enviar nuevamente.	Corregir y reintentar

Detalle del flujo MH en la ficha de Costa Rica.

🇩🇴 Republica Dominicana (DGII)

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

Detalle del flujo DGII en la ficha de Republica Dominicana.

Guia rapida de resolucion

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

1. Leer stage → ubicar la fila en este catalogo.
2. Leer errorDescription → distinguir entre filas que comparten stage (caso Guatemala).
3. Aplicar la accion:
   • 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 automatico 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.