Errors & Status Codes

Every Korba Xchange API call that cannot be completed successfully returns a structured JSON error body. This page lists the error format, all common error codes, and recommendations for handling failures gracefully in your integration.

Error Response Format

Error responses are always JSON with three fields: a boolean success flag, a numeric error_code, and a human-readable error_message. The HTTP status code is typically 200 — use error_code to determine the failure reason rather than relying on HTTP status alone.

{
  "success":       false,
  "error_code":    405,
  "error_message": "Invalid network code"
}

Common Error Codes

The following error codes can be returned by most Korba Xchange API endpoints. Use the error_code value in your application logic to distinguish between failure types and display the appropriate message to your users.

Service-Specific Errors

Some endpoints surface additional error codes beyond the common set above. Refer to the relevant service page for details:

Handling Errors

Follow these practices to build a resilient integration:

• Check error_code, not HTTP status. The API returns HTTP 200 for both success and many application-level errors. Always inspect success and error_code in the response body.
• Retry only transient errors. Errors like 407 (Duplicate Transaction ID) or 405 (Invalid Network Code) are permanent — retrying them will always fail. Only retry on network timeouts or genuine server errors (5xx).
• Use unique transaction IDs. Generate a fresh UUID or timestamp-based reference for every API call. Reusing an ID from a previously submitted transaction will return error 407.
• Validate inputs client-side first. Check phone number format (02xxxxxxxx, 10 digits), amount positivity, and URL validity before calling the API. This prevents avoidable roundtrips for codes 400, 408, 409, and 410.
• Log the full response. Always log the complete JSON error body alongside the request payload. The error_message field often contains actionable detail beyond what the error_code alone conveys.
• Surface user-friendly messages. Map error_code values to customer-facing strings in your UI. Displaying raw API error messages to end users degrades trust and complicates support.