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
• 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
200	000	Pending	Awaiting completion	Continue polling
200	10.x.xxxx	Declined	Business rejection	Do not retry automatically
200	12.x.xxxx	Error	Technical failure	Investigate / retry
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.

Retry Strategy

Retry behavior must be based on error type.

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
• InProcessing

Guidelines:

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

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 indicates state change
• Status Inquiry still returns previous state

Handling:

• Treat as temporary inconsistency
• Retry Status Inquiry

Scenario: Status Updated but Webhook Missing

• Status Inquiry returns final state
• No webhook received

Handling:

• Proceed with 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
• Always validate using Status Inquiry

Scenario: Timeout State

• Transaction not completed in expected time

Handling:

• Treat as non-successful outcome
• Allow retry depending on payment method

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.