🚦 xPOS-Core error codes

Applicable to all countries

The country sheets (Chile, Colombia, …) only document the specific errors of the local tax authority. The stages listed here apply to all countries unless the stage's description says otherwise.

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).
error_description	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 error_description discriminates between rows (typical case: MEGAPRINT_RESPONSE_STAGE in Guatemala).

How to read this catalog

Stage code (HTTP-like)

The code of each row is the HTTP status the POS receives on POST /api/v1/process-documents. The server derives it from the stage: TIMEOUT_ERROR_503 → 503, COMPLIANCE_ERROR_510 → 510 and any other processing error → 400. The WebSocket channel has no HTTP status: it returns the same JSON with its stage.

Errors that occur before the document is processed (malformed JSON, blocked xPOS, missing transformation sheets, expired certificate) do not go through this catalog: see Issuance HTTP status.

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. Includes the duplicate document (VALIDATE_DUPLICITY_STAGE): the "series + number" already exists in the xPOS local database.
503	Timeout: the tax authority did not respond in time and the document may have arrived. Only Colombia, Costa Rica, El Salvador, Guatemala, the Dominican Republic and Peru.
510	Compliance error: the tax authority answered something that is not a valid response, or received the document and did not process it. Only Colombia and Peru.

Recommended actions

Action	What the POS has to do
Correct and retry	Review the POS input, correct what error_description 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.

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

Literal patterns of error_description

Some 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>. In Peru the message is different and the error carries the stored response — see Peru.
• FOLIATOR_STAGE: No tiene folios activos para el tipo de documento = <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.

🇨🇱 Chile (SII)

Code	Stage name	Reason	Suggestion	Action
400	INVALID_REQUEST	The issuer's resolution data (NroResolucion / FechaResolucion) is missing and the document does not carry the CAE node.	Complete the resolution data in the document or in the onboarding and resend.	Correct and retry

The SII is not contacted during the request: the verdict arrives later. Details in the Chile sheet.

🇨🇴 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	FOLIATOR_STAGE	The folio could not be assigned: no folios available or incomplete resolution (CAE) data.	Reload the xPOS configuration or verify the range assignment in GF 3.0.	Reload and retry
400	DIAN_RESPONSE_STAGE	The DIAN rejects or failed to process the submitted document, the certificate has expired or the Rule 90 is invalid. The error_description relays the DIAN message.	Review the document, correct the errors and try to send again.	Correct and retry
503	TIMEOUT_ERROR_503	The DIAN did not respond within 30 seconds (or answered HTTP 408).	Resend the document; if it persists after several attempts, escalate to Gosocket.	Retry
510	COMPLIANCE_ERROR_510	The DIAN answered something that is not a valid response —a SOAP Fault or an HTML page, even with HTTP 403 or 5xx—, or the submission failed.	Resend the document; if it persists, escalate to Gosocket.	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. Both answer HTTP 400.

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
400	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
400	MEGAPRINT_TOKEN_REQUEST	Megaprint rejected the token request (HTTP 4xx) or the response does not carry the token and its validity. If the token fails due to the network, a 5xx error or a timeout and there is no valid one, the document goes to contingency.	Try to send the document again to generate a new token.	Retry
503	TIMEOUT_ERROR_503	Megaprint did not respond in time when registering the document (timeout or HTTP 408/504).	Resend the document; if it persists after several attempts, escalate to Gosocket.	Retry

SAT/Megaprint flow detail in the Guatemala sheet.

🇵🇦 Panama (PAC-GS)

Code	Stage name	Reason	Suggestion	Action
400	PROCESS_PAC_RESPONSE	The PAC rejects or failed to process the submitted document, or answered HTTP 4xx. The error_description 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: any HTTP response other than 2xx (rejection, 401, 403, 404…). The error_description relays the MH message.	Review the document, correct the errors and try to send again.	Correct and retry
503	TIMEOUT_ERROR_503	Hacienda did not respond in time when requesting the token or receiving the document (timeout or HTTP 408/504).	Resend the document; if it persists after several attempts, escalate to Gosocket.	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 error_description relays the DGII message.	Review the document, correct the errors and try to send again.	Correct and retry

| 400 | ET_RESPONSE_STAGE | The DGII rejected the e-CF or answered another HTTP 4xx error (401, 403…). | Review the document or the issuer configuration according to the message and resend. | Correct | | 503 | TIMEOUT_ERROR_503 | The DGII did not respond in time (timeout or HTTP 408/504). When the same e-NCF is resent, xPOS first queries its status and, if it is already final, answers with that status without resending it. | Resend the same document. | Retry |

DGII flow detail in the Dominican Republic sheet.

🇸🇻 El Salvador (Ministry of Finance)

Code	Stage name	Reason	Suggestion	Action
400	VALIDATE_JSON_SCHEMA	The document does not comply with its type's JSON Schema (Pattern B).	Review the document according to the observed fields, correct and resend.	Correct and retry
400	ET_RESPONSE_STAGE	The Ministry of Finance rejected the document.	Review the document, correct the errors and try to send again.	Correct
503	TIMEOUT_ERROR_503	The Ministry of Finance did not respond in time and the document may have arrived.	Resend the document; if it persists after several attempts, escalate to Gosocket.	Retry

Flow detail in the El Salvador sheet.

🇵🇪 Peru (SUNAT / OSE)

Peru does not have a stage of its own for its tax authority: it uses the common stages, and the response's HTTP code already indicates what to do. error_description always carries the SUNAT/OSE code first (2514 - No existe información de receptor…).

Code	Stage name	Reason	Suggestion	Action
503	TIMEOUT_ERROR_503	It is unknown whether it arrived: read timeout, cut after sending, HTTP 500 without Fault, 504, Faults 0125, 0140, 0307.	Resend the same document now with the same number: if the tax authority already had it, xPOS recovers the confirmation.	Retry
510	COMPLIANCE_ERROR_510	The tax authority received it and did not process it: internal error, credentials or configuration, format or packaging (see the classification below).	Fix the cause (or wait a few minutes if it is an internal tax authority error) and resend with the same number: it was not registered.	Correct and retry
400	ET_RESPONSE_STAGE	The tax authority rejected it: CDR other than 0, Faults 2xxx–3xxx, 0100. applicationResponse carries the CDR or the Fault.	Issue with a new folio: the number was used.	Correct
400	SEND_BILL_STAGE	Unexpected error while preparing or sending, for example an unknown destination in the issuer's routing rules.	Review the onboarding configuration; escalate to Gosocket.	Correct
400	VALIDATE_DUPLICITY_STAGE	The number already has a final response (accepted, in contingency, rejected or paper receipt). The error carries what was stored: if it was accepted, the signed XML (output) and the CDR (applicationResponse).	Do not resend: use the XML and the CDR that come in the error.	End of process
400	INVALID_REQUEST	Credit or debit note whose series does not match the document it modifies (BC/BD for receipts, FC/FD for invoices).	Fix the note's series and resend.	Correct and retry

How the SUNAT/OSE code is classified. It arrives as a SOAP Fault or in the CDR, even with HTTP 200 from the service. The specific code takes precedence over the range:

Codes	Class	HTTP to the POS	What the POS does
0125, 0140, 0307; timeout, HTTP 500 without Fault, 504	Uncertain: unknown whether it arrived	503	Resend now, same number
0109, 013x, 020x, 025x	Internal tax authority error	510	Wait a few minutes and resend, same number
0101–0106, 0110–0113, 0152–0154, 0400; HTTP 401/403	Credentials or configuration	510	Fix the configuration and resend, same number
1xxx, 03xx	Format	510	Fix the document and resend, same number
0151, 0155–0161, 1034	Submission packaging	510	Escalate to Gosocket; resend with the same number once resolved
CDR other than 0, 2xxx–3xxx, 0100	Rejection	400	Issue with a new folio
1032, 1033, 2109 on resend	Already registered	Depends on the confirmation	xPOS queries the confirmation — see Resending the same number
1079 on a receipt or receipt note	Declared through the Daily Summary	200	Nothing: the document goes to contingency and is declared in the Daily Summary

Frequent codes:

Code	Meaning	Suggestion
0100	The system cannot answer your request	400: treated as a rejection even without a CDR. Issue with a new folio.
0102	Incorrect user or password	510: usually indicates SUNAT credentials sent to the OSE (or vice versa). Review the per-provider credential configuration in the portal and resend with the same number.
0109	The system cannot answer your request	510: internal tax authority error. Resend the same document in a few minutes.
0159 / 0161	The XML file name does not match the ZIP's	510: a problem with the submission packaging, not the document. Escalate to Gosocket.
1033	The receipt was previously registered	xPOS queries the confirmation: if the tax authority has it accepted and xPOS has the previous attempt, it answers 200 with the original XML. Without a previous attempt it is a numbering collision (400): issue with a new folio and review the correlative assignment.
1034	Submission packaging error	510: escalate to Gosocket. If the document's RUC does not match the origin, issuance fails earlier, at VALIDATE_ISSUER_STAGE.
2223	The file was already submitted	Daily Summary: the batch is rejected and its receipts return to the queue for a new batch. No action required.
0126 / 0127	Foreign or nonexistent ticket	Daily Summary: same as 2223. No action required.
2335	The submitted electronic document has been altered	400: OSE business rejection. Escalate to Gosocket with the transactionId.
2514	There is no receiver information for the document	400: fix the receiver data and issue with a new folio.
2108, 2329, 2600, 2950	Out of deadline	Deadline rejection of a document in contingency: status 3 in the Inbox, note "PLAZO" and a record in "Erroneous documents". Without a formal tax authority response, xPOS uses the code XPOS_PLAZO_VENCIDO. See Deadlines.

SUNAT/OSE flow detail in the Peru sheet.

Quick resolution guide

When a response arrives with message: "Operation Error":

1. Read stage → locate the row in this catalog.
2. Read error_description → distinguish between rows that share a stage (Guatemala case).
3. Apply the action:
   • Correct and retry → correct input and call POST /api/v1/process-documents again.
   • Retry → resend as is.
   • Reload and retry → call PUT /api/v1/reobtain-config and resend.
   • End of process → do not resend; the document is resolved (duplicate, scheduled automatic retry, or requires manual escalation to Gosocket).
4. If stage is not in this catalog → review operational logs with GET /api/v1/db-data/logs/search?uuid=<transactionId> and escalate to Gosocket.