Overview

Error handling is a critical component of any integration with the SIBS Payment Gateway.

Due to the distributed, asynchronous, and eventually consistent nature of the system, integrators must be prepared to handle:

• Technical failures
• Business-level rejections
• Transient inconsistencies
• Edge-case scenarios arising from timing, delivery, and system behavior

This chapter defines how to detect, classify, and handle errors and edge cases to ensure robust and reliable transaction processing.

Error handling strategies must be designed in alignment with the consistency model defined in E.2.6 – Consistency Model: Query vs Webhook.

Error Classification Model

Errors must be interpreted using a multi-layer model, combining:

• HTTP response status
• returnStatus.statusCode
• paymentStatus

Each layer provides different information and must be evaluated together.

HTTP-Level Errors

HTTP status codes indicate the result of the API request itself, not the transaction outcome.

Common HTTP Errors

HTTP Code	Meaning	Handling
400 Bad Request	Invalid request	Validate payload and parameters
401 Unauthorized	Authentication failure	Verify Bearer token and credentials
403 Forbidden	Access denied	Check client permissions and configuration
404 Not Found	Transaction not found	Validate transactionID
500 Internal Server Error	Server-side failure	Retry with backoff

Application-Level Errors (returnStatus)

The returnStatus object provides detailed error information.

Key Principles

• statusCode = "000" indicates successful request processing
  → This does not necessarily imply successful payment completion or successful business outcome.
• Non-zero codes indicate errors or exceptional conditions
• Codes must be interpreted according to C.5 – Status Codes and Error Codes Catalogue

Business-Level Outcomes (paymentStatus)

The paymentStatus field defines the business result of the transaction.

Important Distinction

• A request can be technically successful (statusCode = "000")
• While the transaction is not successful (paymentStatus = Declined, Pending, etc.)

For detailed interpretation of transaction states, refer to E.2.4 – Status Semantics and Interpretation.

Combined Error Interpretation

HTTP Status	returnStatus.statusCode	paymentStatus	Interpretation	Action
200	000	Success	Successful payment	Proceed with business processing
200	000	Pending	Awaiting completion	Continue polling using the defined strategy
200	10.x.xxxx	Declined	Business rejection	Do not retry automatically
200	12.x.xxxx	Error	Technical failure	Investigate and apply retry only if the condition is classified as temporary (Txxxx)
500	—	—	Server error	Retry with backoff

Business actions must always be based on the combined evaluation of all layers and never on a single indicator in isolation.

Final interpretation must always consider all three layers together. No single field (HTTP, returnStatus, or paymentStatus) is sufficient on its own to determine the correct operational action.

Retry Strategy

Retry behavior must be based on error type and must be aligned with the error classification model defined in C.6 – Error Payloads and Handling Guidelines:

• Temporary conditions (statusCode = Txxxx) may be retried using controlled retry strategies (e.g., exponential backoff)
• Validation or business errors (statusCode = Exxxx) must not be retried automatically and require correction or user-driven resolution

Retryable Errors

• 500 Internal Server Error
• Temporary network failures
• Transient Error states

Guidelines:

• Use exponential backoff
• Limit retry attempts
• Avoid synchronized retries

Non-Retryable Errors

• 400 Bad Request
• 401 Unauthorized (until fixed)
• 403 Forbidden
• Declined payment states

Guidelines:

• Do not retry automatically
• Correct configuration or user input

Retry mechanisms must be designed to avoid amplification of system load under failure conditions.

Handling Transient States

Transient states include:

• Pending

Guidelines:

• Continue polling using the defined strategy
• Do not trigger business actions
• Combine with webhook monitoring

Polling strategies, backoff models, and stop conditions are described in E.2.5 – Polling Strategy and Best Practices.

Edge Case Scenarios

Scenario: Transaction Not Found (404)

Possible causes:

• Invalid transactionID
• Query executed before transaction is fully registered

Handling:

• Validate identifier
• Retry after short delay if recently created

Scenario: Webhook Received but Status Not Updated

• Webhook event and queried state differ temporarily

Handling:

• Treat as temporary inconsistency
• Retry Status Inquiry APIs

Reconciliation patterns and transaction-state validation strategies are described in E.2.7 – Reconciliation Patterns.

Scenario: Status Updated but Webhook Missing

• Status Inquiry APIs return final state
• No webhook received

Handling:

• Proceed with appropriately validated business logic
• Log missing webhook for monitoring

Scenario: Duplicate Webhook Events

• Same webhook delivered multiple times

Handling:

• Ensure idempotent processing
• Avoid duplicate actions

Scenario: Out-of-Order Webhook Events

• Events received in incorrect sequence

Handling:

• Ignore ordering
• Validate using Status Inquiry APIs when no final webhook is available or when additional confirmation is required

Scenario: Timeout State

• Transaction not completed in expected time

Handling:

• Treat as potentially unresolved outcome requiring reconciliation or additional validation
• Allow retry only if the underlying condition is classified as temporary (statusCode = Txxxx) or if the payment method explicitly supports retry scenarios

Scenario: Long-Running Transactions

• Transactions remain in Pending for extended periods

Handling:

• Stop active polling after defined duration
• Use batch reconciliation or webhook monitoring

Defensive Integration Practices

Integrators must implement:

• Defensive parsing of response payloads
• Handling of missing or optional fields
• Protection against unexpected values or states

Observability and Logging

Effective error handling requires visibility:

• Log all failed requests and responses
• Track error codes and frequencies
• Monitor retry patterns
• Detect abnormal error rates

Alerting and Escalation

Systems should trigger alerts when:

• Error rates exceed thresholds
• Transactions remain unresolved beyond expected time
• Reconciliation failures occur

Integration Anti-Patterns

The following must be avoided:

• Ignoring HTTP status codes
• Treating statusCode = "000" as payment success
• Retrying non-retryable errors
• Acting on transient states
• Failing to log or monitor errors

Key Integration Principles

• Always evaluate all three layers: HTTP, returnStatus, and paymentStatus
• Distinguish between technical and business errors
• Implement controlled retry strategies
• Design for transient failures and inconsistencies
• Ensure idempotent and safe error handling

Summary

Error handling in the SIBS Payment Gateway requires a multi-layered and defensive approach.

By correctly interpreting:

• HTTP response status
• Application-level result codes (returnStatus)
• Business transaction state (paymentStatus)

Integrators can:

• Handle failures reliably
• Avoid incorrect business actions
• Build resilient and fault-tolerant systems

Proper error handling is essential for ensuring robust, scalable, and production-ready payment integrations.