🚦 Códigos de errores xPOS-Core
Aplicable a todos los países
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)
xPOS-Core usa cinco códigos para clasificar el evento. No se mapean 1:1 al HTTP devuelto por la API REST: son una etiqueta operativa interna.
| 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. |
404 | Documento duplicado: la "serie + número" ya existe en la base local de xPOS. |
503 | Timeout: la entidad tributaria tardo mas de 30 segundos en responder. |
510 | Error de cumplimiento: excepción al enviar a la entidad tributaria (red, autenticación, formato rechazado). |
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.
18 de 18 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 | 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 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
error_descriptionAlgunas 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 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.
🇨🇴 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 | DIAN_RESPONSE_STAGE | La DIAN rechaza o no logro procesar el documento enviado. El error_description 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 | 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 |
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 configuración del xPOS o verificar la asignación 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 | Acción |
|---|---|---|---|---|
200 | PROCESS_PAC_RESPONSE | El PAC rechaza o no logro procesar el documento enviado. 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. El error_description 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 | 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 |
Detalle del flujo DGII en la ficha de Republica Dominicana.
🇵🇪 Perú (SUNAT / OSE)
Perú no tiene una etapa propia de su entidad tributaria: los rechazos de SUNAT o del OSE llegan por ET_RESPONSE_STAGE (el error_description trae el mensaje de la autoridad y applicationResponse la CDR) y los fallos del envío por SEND_BILL_STAGE. Además, inputType=txt no está soportado en Perú y produce SERVER_PROCESS_REQUEST_STAGE — la acción es cambiar a json o xml.
Cómo interpretar el código numérico de SUNAT/OSE (viene dentro del mensaje, como SOAP Fault — puede llegar incluso con HTTP 200):
| Rango del código | Significado | Qué hace xPOS |
|---|---|---|
< 1000 | Excepción de sistema de la autoridad | El documento pasa a contingencia y se regulariza después. |
>= 1000 | Rechazo del comprobante o del archivo | Rechazo definitivo: corregir el documento y emitir uno nuevo. Reintentar el mismo no sirve. |
Códigos frecuentes:
| Código | Significado | Sugerencia |
|---|---|---|
0102 | Usuario o contraseña incorrectos | Suele indicar credenciales de SUNAT enviadas al OSE (o viceversa). Revisar la configuración de credenciales por proveedor en el portal. |
0159 / 0161 | El nombre del archivo XML no coincide con el del ZIP | Escalar a Gosocket: es un problema de armado del envío, no del documento. |
1033 | El comprobante fue registrado previamente | La serie-número ya existe en la autoridad. No reintentar con el mismo número. |
1034 | El RUC del emisor no coincide | Revisar que el origin y el RUC del emisor del documento sean el mismo. |
2223 | El archivo ya fue presentado | Aplica al Resumen Diario: xPOS lo re-declara automáticamente en el resumen siguiente. No requiere acción. |
2335 | El documento electrónico ingresado ha sido alterado | Rechazo de negocio del OSE. Escalar a Gosocket con el transactionId. |
Detalle del flujo SUNAT/OSE en la ficha de Perú.
Guia rápida de resolución
Cuando llega un response con message: "Operation Error":
- Leer
stage→ ubicar la fila en este catalogo. - Leer
error_description→ distinguir entre filas que compartenstage(caso Guatemala). - 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-configy reenviar. - Fin del proceso → no reenviar; el documento esta resuelto (duplicado, reintento automático programado, o requiere escalamiento manual a Gosocket).
- Corregir y reintentar → corregir input y volver a llamar
- Si
stageno esta en este catalogo → revisar logs operativos conGET /api/v1/db-data/logs/search?uuid=<transactionId>y escalar a Gosocket.