Overview

This section defines the categorization and responsibility model for SPG error codes, establishing how different types of errors must be interpreted and handled by merchant systems.

While C.5.1 API-Level Status Codes defines the API-level structure of error responses, this section defines:

• how errors are categorized
• who is responsible for resolving them
• what actions must be taken in each case

This model is essential to ensure correct operational behavior, particularly in scenarios involving retries, validation failures, and external system dependencies.

Error Categories

SPG error codes can be classified into the following categories, based on their nature and handling implications.

Validation Errors

These errors occur when the request is invalid or incomplete.

Typical characteristics:

• malformed payload
• missing or incorrect parameters
• invalid merchant, terminal, or configuration

Examples:

• E0101 → invalid request
• E0002 → missing or invalid data

Handling:

• must be corrected before retry
• must not be retried automatically
• require changes in request construction or configuration

Business Errors (Declined Operations)

These errors represent valid requests that were rejected at business level.

Typical characteristics:

• insufficient funds
• user rejection
• issuer decline
• fraud detection

Examples:

• E0119 → declined operation
• issuer-related declines in payment flows

Handling:

• must not be retried automatically
• may be retried only with user intervention
• must be communicated clearly to the end user

Technical Errors

These errors occur due to failures in system processing.

Typical characteristics:

• internal errors
• processing failures
• unexpected conditions

Examples:

• E0301 → transaction not found or processing error (depending on context)

Handling:

• may require retry depending on context
• must be logged and monitored
• may require escalation if persistent

Temporary Errors

These errors indicate transient conditions that may be resolved automatically.

Typical characteristics:

• temporary system unavailability
• network issues
• external dependency failure

Examples:

• T9999 → temporary internal error

Handling:

• safe to retry
• must use retry strategy with backoff
• must avoid immediate repeated retries

Conflict and State Errors

These errors occur when the operation conflicts with the current transaction state.

Typical characteristics:

• duplicate operations
• already processed transactions
• invalid state transitions

Examples:

• E0124 → transaction already processed
• E0127 → transaction already made

Handling:

• must not be retried blindly
• require reconciliation with current transaction state
• must use status inquiry before further action

Responsibility Model

Each error must be interpreted in terms of who is responsible for resolving it.

This dimension is critical for determining the correct operational response.

Merchant Responsibility

Errors caused by incorrect integration, configuration, or request data.

Examples:

• invalid payload
• incorrect terminal configuration
• missing parameters

Action:

• fix request or configuration
• do not retry without correction

User / Client Responsibility

Errors caused by user actions or decisions.

Examples:

• payment declined by user
• authentication not completed
• insufficient funds

Action:

• inform user
• allow retry with user intervention

SIBS / System Responsibility

Errors caused by internal or external system conditions.

Examples:

• temporary system errors (T9999)
• processing failures
• external service unavailability

Action:

• retry with backoff
• monitor and escalate if persistent

Relationship Between Category and Responsibility

Error category and responsibility must be interpreted together.

Category	Typical Responsibility	Retry Strategy
Validation	Merchant	No retry until fixed
Business (Declined)	User / Issuer	Retry with user action
Technical	SIBS / System	Conditional retry
Temporary	SIBS / System	Retry with backoff
Conflict / State	Merchant / System	Reconcile before retry

This combined interpretation ensures that systems behave correctly under all error conditions.

Retry Strategy Principles

Retries must be applied selectively and based on error classification.

• Never retry validation errors
• Never retry business declines automatically
• Retry temporary errors with exponential backoff
• Retry technical errors only when safe and idempotent
• Always validate transaction state before retrying state-dependent operations

Retry behavior must always respect the transaction lifecycle and avoid duplicate or conflicting operations.

Relationship with Other Code Domains

The classification and responsibility model defined in this section applies across all code domains, including:

• API-level codes (see C.5.1 API-Level Status Codes)
• operational and legacy codes (see C.5.3 Legacy / Detailed Error Codes)
• payment-method-specific codes (see C.5.4 Payment Method-Specific Error Domains)

While different domains provide different levels of detail, the handling logic defined here remains consistent.

Implementation Considerations

Merchant systems must implement error handling logic that:

• classifies errors according to category and responsibility
• applies appropriate retry strategies
• prevents duplicate or conflicting operations
• integrates with transaction state validation
• ensures proper logging and monitoring

Failure to implement this model correctly may result in:

• incorrect retries
• duplicate transactions
• inconsistent system behavior
• degraded user experience

Final Consideration

Error handling in SPG is not based solely on code values, but on a combination of:

• error category
• responsibility
• transaction state
• operational context

This section defines the model required to interpret these dimensions consistently and to implement safe and reliable error handling across all SPG integrations.

This model must be applied together with the structures defined in:

• C.5 Status Codes and Error Codes Mapping → interpretation model
• C.5.1 API-Level Status Codes → API-level codes
• C.5.3 Legacy / Detailed Error Codes → detailed operational codes
• C.5.4 Payment Method-Specific Error Domains → payment method-specific behavior