The Spanish version is the authoritative reference. View in Spanish
🚦 xPOS-Core error codes
Applicable to all countries
Source
Catalog maintained by the xPOS-Core team based on the internal runbook POS response/error codes. It is synchronized against the stages emitted by process-documents.
Where the error appears in the response
When xPOS-Core fails to complete an operation, the protocol response brings these three fields populated:
| Field | What it contains |
|---|---|
message | Operation Error (in case of error) or Operation Successful (when the stage is 200 — the document proceeded with an observation). |
stage | The name of the stage that triggered the event (Stage name column of the catalog). |
errorDescription | The human-readable message that describes the specific cause (Message column). |
The stage is the key to locate the correct row of the catalog. When the same stage can be triggered by different reasons, the errorDescription discriminates between rows (typical case: MEGAPRINT_RESPONSE_STAGE in Guatemala).
How to read this catalog
Stage code (HTTP-like)
xPOS-Core uses five codes to classify the event. They do not map 1:1 to the HTTP returned by the REST API: they are an internal operational label.
| Code | Meaning |
|---|---|
200 | Operation completed with an observation. The document proceeded through its flow, but there was a relevant note (contingency, fallback, scheduled retry). |
400 | Validation or transformation error. xPOS could not build or send the document; requires action from the POS or from product. |
404 | Duplicate document: the "series + number" already exists in the xPOS local database. |
503 | Timeout: the tax authority took more than 30 seconds to respond. |
510 | Compliance error: exception when sending to the tax authority (network, authentication, rejected format). |
Recommended actions
| Action | What the POS has to do |
|---|---|
| Correct and retry | Review the POS input, correct what errorDescription indicates and resend. |
| Retry | Resend the same document without changes — transient error or temporary configuration. |
| Reload and retry | Ask the xPOS to re-download its configuration (folios, certificates, templates) and resend. Applies when the problem is a local state issue. |
| Correct | Review the input but without resending automatically (the document was already notified to the tax backend). |
| End of process | No POS action required — xPOS manages the retry or the condition is already resolved. |
Input type
The Input Type column indicates the inputType values (query param of POST /api/v1/process-documents) that can trigger the stage. All means it applies to any inputType supported by the country.
Errors common to all countries
These stages are part of the general xPOS-Core pipeline. They are ordered by the execution sequence within 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 |
Literal patterns of
errorDescriptionSome stages return a message with a stable format that the POS can parse:
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> ....
The rest of the stages relay the original message from the library or the tax authority, without a guaranteed format.
Country-specific errors
When the stage is triggered by the local tax authority (or an intermediate PAC), the catalog adds rows that only apply to that country.
🇨🇴 Colombia (DIAN)
| Code | Stage name | Reason | Suggestion | Action |
|---|---|---|---|---|
400 | FIND_SERIE_AND_NUMBER_STAGE_CO | The search for the series and folio of the electronic document could not be completed. | Check that the document has the series and folio; if it persists, contact Gosocket. | Correct and retry |
400 | DIAN_RESPONSE_STAGE | The DIAN rejects or failed to process the submitted document. The errorDescription relays the DIAN message. | Review the document, correct the errors and try to send again. | Correct and retry |
DIAN flow detail in the Colombia sheet.
🇬🇹 Guatemala (Megaprint / SAT)
MEGAPRINT_RESPONSE_STAGE is triggered for two different reasons. To distinguish them, inspect the error_description field of the response.
| Code | Stage name | Reason | Suggestion | Action |
|---|---|---|---|---|
400 | MEGAPRINT_RESPONSE_STAGE | Megaprint rejects the document or failed to process it. The error_description field brings the detail (e.g.: FEL_GEN102 RESTRICTION_PATTERN). | Review error_description, correct the errors and try to send the document again. | Correct |
400 | MEGAPRINT_RESPONSE_STAGE (duplicity) | error_description starts with Notificacion: Documento enviado anteriormente con el folio XXXXXX-XXXXXXX. Megaprint already processed and accepted the document previously. | No action required. The POS can confirm the acceptance of the document with number XXXXX-XXXXXX. | End of process |
200 | ACCESS_NUMBER_GENERATION_STAGE | A contingency folio sub-range is not available to assign to the document. | Check whether the xPOS has downloaded a contingency folio sub-range. Reload the xPOS configuration or verify the range assignment in GF 3.0. | Reload and retry |
200 | MEGAPRINT_TOKEN_REQUEST | Problems with the token assigned to the xPOS. | Try to send the document again to generate a new token. | Retry |
SAT/Megaprint flow detail in the Guatemala sheet.
🇵🇦 Panama (PAC-GS)
| Code | Stage name | Reason | Suggestion | Action |
|---|---|---|---|---|
200 | PROCESS_PAC_RESPONSE | The PAC rejects or failed to process the submitted document. The errorDescription relays the PAC message. | Review the document, correct the errors and try to send again. | Correct and retry |
PAC-GS flow detail in the Panama sheet.
🇨🇷 Costa Rica (Ministry of Finance)
| Code | Stage name | Reason | Suggestion | Action |
|---|---|---|---|---|
400 | MINISTERIO_HACIENDA_RESPONSE_STAGE | The Ministry of Finance (MH) rejects or failed to process the submitted document. The errorDescription relays the MH message. | Review the document, correct the errors and try to send again. | Correct and retry |
MH flow detail in the Costa Rica sheet.
🇩🇴 Dominican Republic (DGII)
| Code | Stage name | Reason | Suggestion | Action |
|---|---|---|---|---|
400 | SEND_RFCE_TO_DGII_STAGE | The DGII rejects or failed to process RFCE-type documents. The errorDescription relays the DGII message. | Review the document, correct the errors and try to send again. | Correct and retry |
DGII flow detail in the Dominican Republic sheet.
Quick resolution guide
When a response arrives with message: "Operation Error":
- Read
stage→ locate the row in this catalog. - Read
errorDescription→ distinguish between rows that share astage(Guatemala case). - Apply the action:
- Correct and retry → correct input and call
POST /api/v1/process-documentsagain. - Retry → resend as is.
- Reload and retry → call
PUT /api/v1/reobtain-configand resend. - End of process → do not resend; the document is resolved (duplicate, scheduled automatic retry, or requires manual escalation to Gosocket).
- Correct and retry → correct input and call
- If
stageis not in this catalog → review operational logs withGET /api/v1/db-data/logs/search?uuid=<transactionId>and escalate to Gosocket.