Overview
This section defines the operational error code model used by SPG, providing detailed diagnostic information for transaction processing across different operations and payment methods.
Unlike the API-level status codes defined in C.5.1 API-Level Status Codes, which represent a normalized response layer, the codes presented in this section provide:
- granular error diagnostics
- operation-specific failure conditions
- ownership and responsibility indicators
- recommended corrective actions
These codes are typically structured in formats such as:
12.110.xxxx→ operation-level error domains10.10x.xxxx→ payment-method-specific operational domains90.xxxx→ extended or auxiliary operational scenarios
They must be interpreted in conjunction with:
- the API-level response (see C.5.1 API-Level Status Codes)
- the error categorization and responsibility model (see C.5.2 Error Code Categories and Responsibility Model)
- the transaction state model (see C.5 Status Codes and Error Codes Mapping)
Role of Operational Error Codes
Operational error codes provide detailed insight into why an operation failed or behaved in a certain way.
They extend the API-level model by:
- identifying the exact failure condition
- indicating which system component is responsible
- providing actionable guidance for resolution
Typical information included in these tables:
- error code
- message to merchant
- message to client
- owner (Merchant, SIBS, Client)
- recommended action (“What to do”)
These elements are critical for:
- debugging and troubleshooting
- operational monitoring
- support and incident analysis
- implementing precise handling strategies
Relationship with API-Level Codes
Operational error codes do not replace API-level status codes.
Instead, they provide additional diagnostic depth.
For example:
- API-level response may return
E0119(declined operation) - Operational code may specify the exact reason for decline
Both layers must be interpreted together:
- API-level codes → classify the outcome
- Operational codes → explain the cause
Operational Code Domains
Operational error codes are organized by operation type and processing domain.
Each domain corresponds to a specific part of the SPG lifecycle.
Checkout Request
| Error code | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 12.110.1201 | Wrong parameterization in the amount, expiration date, token, Merchant code or terminal code. | Please try again later. | Merchant | Checkout and payment received data for reference generation is incomplete, has to send (Amount and Expiration date). |
| 12.110.1202 | Wrong parameterization, Missing data. | Please try again later. | Merchant | Evaluate if the message is correctly formatted (Check if it is parameterizing correctly) according to the SLA. |
| 12.110.1203 | SIBS Internal error, Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1204 | SIBS Internal error, Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1205 | SIBS Internal error, Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1206 | SIBS Internal error, Please try again later. | Service not available, please try later. | SIBS | Try again later. |
Payment Request
| Error codes | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 12.110.1301 | Wrong parameterization, Missing data. | Service not available, please try later. | Merchant | Please check parameterization on the checkout, its needed to invoke the form script to send the signature (Form context). Please verify if the amount, expiration date, token, Merchant code or terminal code are being sent correctly. |
| 12.110.1302 | Wrong parameterization, Missing data. | Service not available, please try later. | Merchant | Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA. |
| 12.110.1303 | SIBS Internal error, Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1304 | Wrong parameterization, Missing data. | Service not available, please try later. | Merchant | Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA. |
| 12.110.1305 | Wrong parameterization in payment type (Authorisation, Purchase, Capture or Refund). | Service not available, please try later. | Merchant | Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA |
| 12.110.1306 | Wrong parameterization in payment method (Card, MBWAY, or Reference) | Service not available, please try later. | Merchant | Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA. |
| 12.110.1307 | Wrong parameterization in amount, expiration date, token, Merchant code or terminal code. | Service not available, please try later. | Merchant | Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA. |
| 12.110.1308 | Wrong amount. | Service not available, please try later. | Merchant | Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA. |
| 12.110.1309 | Wrong Currency | Service not available, please try later. | Merchant | Evaluate if the message is correctly formatted and no data is missing (Check if it is parameterizing correctly) according to the SLA. |
| 12.110.1310 | Transaction already finalized | Service not available, please try later. | Merchant | Need to input a valid transaction Id that it is not finalized . |
| 12.110.1311 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1312 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Payment does not fail, only tokenisation fails. No Action . |
| 12.110.1313 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Payment does not fail, only tokenisation fails. No Action. |
| 12.110.1314 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1315 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1316 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1317 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1318 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1319 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1320 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1321 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1322 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1323 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1324 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
Status Inquiry
| Error code | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 12.110.1401 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1402 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1403 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1404 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1405 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1406 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1407 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1408 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1409 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1410 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1411 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1412 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
Backoffice Operations
| Error code | Message to the Merchant | Merchant to the Client | Owner | What to do? |
|---|---|---|---|---|
| 12.110.1901 | Wrong parameterization in the amount, expiration date, token, Merchant code or terminal code. | Please try again later. | Merchant | Checkout and payment received data for reference generation is incomplete, has to send (Amount and Expiration date). |
| 12.110.1902 | Wrong parameterization, Missing data. | Please try again later. | SIBS | Try again later. |
| 12.110.1903 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1904 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1905 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1906 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1907 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1908 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1909 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1910 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1911 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1912 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1913 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1914 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1915 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later, doing a Checkout Status. |
| 12.110.1916 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
MB WAY
| Error code | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 90.000.0001 | Exception – Time Out -Error in message format | SIBS Technical Issue, please try later | SIBS | Please try again or later – issue to be solved by SIBS |
| 01.106.0001 | After the operation was successful, was refused by the cardholder | Operation Refused by you, try again. | Client | Repeat the operation. |
| 10.106.0001 | Used the wrong or without contract Terminal | Please choose a valid terminal, or try later. | Merchant | Please check if this terminal is the correct and have the services you are trying to use. |
| 01.106.0002 | Card refused MB WAY alias associated | Card refused, MBWAY alias already associated | Client | This card already has an alias associated, Please use another card. |
| 90.000.0002 | Time out | SIBS Technical Issue, please try later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 10.106.0002 | Several reasons (connectivity’s, server down, etc.) | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 90.000.0003 | Wrong message parameterisation | SIBS Technical Issue try again later | SIBS | Please try Again or later – Check message parameterisation. |
| 10.106.0003 | Issue with MBWAY- Wrong alias | Issue with MBWAY- Wrong alias, try again. | Client | Error in alias, please check format, typing or possible duplication |
| 10.106.0004 | Issue with MBWAY- Alias format | Issue with MBWAY- Alias format, try again. | Client | Error in alias, please check format, typing or possible duplication |
| 10.106.0005 | Issue with MBWAY- Alias Duplication | Issue with MBWAY- Alias Duplication, try again. | Client | Error in alias, please check format, typing or possible duplication |
| 10.106.0006 | Issue with MBWAY- Inexistent alias | Issue with MBWAY- inexistent alias, try again. | Client | Error in alias, please check format, typing or possible duplication |
| 10.106.0007 | Duplicated transaction | Transaction ID equal to other transaction already finished | Merchant | Please verify which transaction ID is being sent. |
| 10.106.0008 | Issue with the Operation (invalid) | Operation Invalid, declined or not found, try again later. | Merchant | Please verify the operation details and try again |
| 10.106.0009 | Issue with the Operation (declined) | Operation Invalid, declined or not found, try again later. | Merchant | Please verify the operation details and try again |
| 10.106.0010 | Issue with the Operation (not found) | Operation Invalid, declined or not found, try again later. | Merchant | Please verify the operation details and try again |
| 10.106.0011 | Issue with MBWAY- alias | Not Possible to ASSOCIATE MBWAY alias, try again. | Client | Error in alias, please verify if the alias is already being used. |
| 10.106.2632 | Authorized Payment Unknown | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 10.106.2639 | Authorized Payment Invalid Operation Type | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 10.106.2640 | Authorized Payments Service Disabled | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 10.106.2641 | Invalid Authorized Payment Status | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 10.106.2644 | Invalid Authorized Payment Values | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 10.106.2645 | Invalid Authorized Payment Service Provider | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 10.106.2699 | Invalid Authorized Payment Context | Please try again later | SIBS | Please try Again or later – Evaluate if the message is correctly fulfilled (Check if it is parameterizing correctly). |
| 90.106.2699 | SIBS Internal error, Please try again later. | Please try again later | SIBS | Try again later. |
MULTIBANCO
| Error code | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 10.107.0001 | Invalid payment entity | Entity not valid, Try again later. | Merchant | Please verify that the correct Merchant entity is being used. |
| 10.107.0002 | Invalid reference minimum amount | Invalid reference minimum, amount please try again. | Merchant | Please verify the parameterization in the amount. |
| 10.107.0003 | Invalid reference maximum amount | Invalid reference maximum amount please try again. | Merchant | Please verify the parameterization in the amount. |
| 10.107.0004 | Invalid currency | Invalid currency try again. | Merchant | Please verify the parameterization in the currency accepted. |
| 10.107.0005 | Invalid NIB | Invalid NIB please try again. | Client | Please verify you are using the correct NIB. |
| 10.107.0006 | Invalid reference initial date time | Invalid reference initial date time try again. | Merchant | Please verify the parameterization in time accepted. |
| 10.107.0007 | Invalid reference limit date time | Invalid reference limit date time try again. | Merchant | Please verify the parameterization in time accepted. |
| 10.107.0008 | Invalid Email | Invalid Email try again. | Client | Please insert the email used on the registration. |
| 10.107.0009 | Payment entity is not active | Payment entity is not active, try later | Merchant | Please verify your entity, if it is the one in the SLA. |
| 10.107.0010 | Reference generation not allowed for the payment entity | Reference generation not allowed try later. | Merchant | Please verify your entity, if it is the one in the SLA. |
| 10.107.0011 | Payment reference not found | SIBS Internal error, Please try again later. | SIBS | SIBS Internal error, Please try again later. |
| 10.107.0012 | Payment reference is cancelled | Payment reference is cancelled. | Merchant | Please verify your reference was cancelled. |
| 10.107.0013 | Payment reference already paid | Payment reference already paid. | Merchant | Please verify your reference is already paid. |
| 10.107.0014 | Invalid operation | Invalid operation, try later. | SIBS | SIBS Internal error, Please try again later. |
| 90.000.0001 | Exception | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 90.000.0003 | Error in message format | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
Card Payments
| Error code | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 10.105.0001 | Invalid payment entity. | Entity not valid, please try again later. | Merchant | Please verify that the correct Merchant entity is being used. |
| 10.103.0003 | No card record. | Card not valid please try again later. | SIBS | Please verify log. |
| 10.103.0004 | Not sufficient funds | Not sufficient funds, try again | Client | Please assure that the account has enough funds. |
| 10.103.0005 | Invalid card number | Card number not valid try again. | Client | Please insert the correct card number. |
| 10.103.0006 | Expired card | Expired card, please verify with your bank. | Client | Please note that your card has expired. |
| 10.103.0007 | Card Cancelled | Your card has been Cancelled please verify with your bank. | Client | Please verify with your bank. |
| 10.103.0008 | Inactive card | Inactive card, please verify with your bank. | Client | Please verify with your bank. |
| 10.103.0009 | This card has been reported as stolen. | Pick-up card, please verify with your bank. | Client | Please verify with your bank. |
| 10.103.0010 | Blocked card | Blocked Card, please verify with your bank. | Client | Please verify with your bank. |
| 10.103.0011 | Invalid CVV | Invalid CVV, please double check | Client | Please insert the correct CVV number. |
| 10.103.0012 | Card Limit exceeded | Card Limit exceeded, please verify with your bank. | Client | Please verify with your bank. |
| 10.103.0013 | Wrong expiry date. | Wrong expiry date, please double check | Client | Please insert the correct card expiration date. |
| 10.105.0014 | Invalid refund amount. | N/A | Merchant | Please assure that the Refund is equal to the total amount or less. |
| 10.103.0015 | Invalid card (Cannot Process Operation – Fraud) | Invalid card, please verify with your bank. | Client | Please verify with your bank. |
| 10.105.0016 | Invalid expiry date. | Invalid expiry date, please double check | Client | Please verify with your bank or insert a valid Expiration date. |
| 10.103.0017 | Wrong code. | Wrong Code, please double check | Client | Please try again. |
| 10.103.0018 | Wrong code, 3 tentative exceed. | Wrong Code, 3 tentative exceed, please verify with your bank. | Client | Please contact you bank. |
| 10.105.0017 | Cancellation amount exceeds authorized amount. | Cancellation amount exceeds authorized amount | Merchant | Please assure that the cancellation is equal to the total amount or less. |
| 10.105.0018 | Authorisation is cancelled. | The Authorisation was cancelled | Merchant | Please assure that the Authorisation is not finalized. |
| 10.105.0019 | Authorisation is already used. | N/A | Merchant | Please assure that this Authorisation belongs to this transaction. |
| 10.105.0020 | Purchase amount exceeds authorized amount. | N/A | Merchant | Please assure that the purchase is Equal the total amount or less. |
| 10.105.0021 | Purchase already refunded. | Purchase already refunded | Merchant | Please assure that this operation belongs to this transaction. |
| 10.105.0022 | Amount is below commission. | Amount is below commission | Merchant | Please assure the minimum amount to allow the fee charge |
| 90.000.0001 | Exception. | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
| 90.000.0003 | Error in message format. | SIBS Technical Issue try again later | SIBS | Please try Again or later – Issue to be solved by SIBS |
Authorized Payments / Recurring Operations
| Error code | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 10.110.2301 | Authorized Payment status validation error | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2631 | Authorized Payment Transaction Cancelled | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2632 | Authorized Payment Transaction Unknown | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2633 | Authorized Payment Transaction Rejected | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2634 | Authorized Payment Transaction Refused | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2635 | Authorized Payment Transaction Reverted | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2636 | Authorized Payment Transaction Time Out | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2637 | Authorized Payment Transaction Expired | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2638 | Authorized Payment Transaction Unknown | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2639 | Authorized Payment Transaction Not Valid | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2640 | Authorized Payment Transaction Inactive | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2641 | Authorized Payment Transaction Not Valid | Please try again later. | Merchant | Evaluate what is the status of the Authorized Payment. |
| 10.110.2642 | Authorized Payment Transaction Token Not Valid | Please try again later. | Merchant | Evaluate if the Authorized Payment token is correct |
| 10.110.2643 | Invalid Authorized Payment Context | Please try again later. | Merchant | Evaluate if the message is correctly fulfilled (Check if it is parameterizing correctly). |
| 10.110.2670 | Invalid Authorized Payment Terminal | Please try again later. | Merchant | Validate terminal identification used in transaction. |
| 10.110.2671 | Invalid Authorized Payment Payment Method | Please try again later. | Merchant | Evaluate if the message payment method is correctly fulfilled (Check if it is parameterizing correctly). |
| 10.110.2672 | Invalid Authorized Payment Identification is present. | Please try again later. | Merchant | Evaluate Authorized Payment Identification presence. |
| 10.110.2673 | Missing Authorized Payment Data | Please try again later. | Merchant | Evaluate supplied Authorized Payment Mandatory Data. |
| 10.110.2674 | Merchant Authorized Payment Service Inactive. | Please try again later. | Merchant | Evaluate if Authorized Payment service parameterization is been completely performed (activation, monthly amount limits, name and logo). |
| 10.110.2675 | Merchant Authorized Payment Already Exists. | Please try again later. | Merchant | Evaluate the existence of another Authorized Payment with same input data. |
| 10.110.2676 | Authorized Payment Unavailable | Please try again later. | Merchant | Evaluate if the mandate identification is correctly fulfilled. |
| 10.110.2677 | Authorized Payment Unknown | Please try again later. | Merchant | Evaluate if the Authorized Payment identification is correctly fulfilled. |
| 10.110.2678 | Authorized Payment is Cancelled | Please try again later. | Merchant | Evaluate if the Authorized Payment identification is correctly fulfilled. |
| 10.110.2680 | Wrong parameterization in Authorized Payment creation elements. | Please try again later. | Merchant | Evaluate if the message is correctly fulfilled (Check if it is parameterizing correctly). |
| 10.110.2681 | Wrong parameterization in Authorized Payment creation elements. | Please try again later. | Merchant | Evaluate if the message is correctly fulfilled (Check if it is parameterizing correctly). |
QR Code Generation
| Error code | Message to the Merchant | Message to the Client | Owner | What to do? |
|---|---|---|---|---|
| 12.110.1101 | Wrong data, check Signature, code and Terminal | Service not available, please try later. | Merchant | Check transaction signature, Merchant code and Terminal id are in place. |
| 12.110.1102 | SIBS Internal error, Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1103 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Check transaction ID, transaction already initiated, finish or cancel this transaction. |
| 12.110.1104 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1105 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
| 12.110.1106 | SIBS Internal error. Please try again later. | Service not available, please try later. | SIBS | Try again later. |
Interpretation Principles
Operational error codes must be interpreted using the following principles:
- They provide detailed diagnostic information, not the primary outcome classification
- They must be evaluated together with API-level
statusCode - They must be mapped to the error categories defined in C.5.2 Error Code Categories and Responsibility Model
- They may vary depending on operation type and payment method
- They may expose more specific causes than API-level codes
Handling Implications
Operational error codes must be used to refine handling strategies defined in C.5.2 Error Code Categories and Responsibility Model.
For example:
- validation-related operational codes → confirm merchant responsibility
- issuer-related operational codes → confirm user/business decline
- system-related operational codes → confirm retry eligibility
- state-related operational codes → enforce reconciliation before retry
These codes enable more precise decision-making without changing the overall handling model.
Relationship with Responsibility Model
The operational tables include an explicit “Owner” dimension, which directly maps to the responsibility model defined in C.5.2 Error Code Categories and Responsibility Model.
This allows systems to:
- determine whether the issue must be resolved by the merchant, user, or system
- apply the correct retry or correction strategy
- route issues to the appropriate operational channel
Implementation Considerations
Merchant systems must:
- log operational error codes alongside API-level responses
- use operational codes for diagnostics and monitoring
- map operational codes to error categories defined in C.5.2 Error Code Categories and Responsibility Model
- avoid using operational codes as the sole decision driver
- ensure consistency between operational diagnostics and transaction state
Operational codes are particularly important in:
- production debugging
- reconciliation processes
- support and incident handling
Final Consideration
Operational error codes represent the deep diagnostic layer of SPG, providing detailed insight into transaction processing behavior.
They must always be interpreted together with:
- C.5 Status Codes and Error Codes Mapping → interpretation model
- C.5.1 API-Level Status Codes → API-level status codes
- C.5.2 Error Code Categories and Responsibility Model → error categorization and responsibility
- C.5.4 Payment Method-Specific Error Domains → payment method-specific domains
A correct implementation ensures:
- accurate diagnosis of failures
- proper responsibility attribution
- safe and precise handling of all operational scenarios