Skip to main content

Error Response Format

All errors follow the RFC 7807 Problem Details specification:

HTTP Status Codes

OK
Request successful
Created
Resource created successfully
Bad Request
Invalid request parameters or malformed request body
Unauthorized
Missing or invalid authentication credentials
Not Found
Requested resource not found
Unprocessable Content
Request validation failed or business logic error

Common Error Scenarios

Authentication Errors

Causes:
  • Missing Authorization header
  • Invalid API key
  • Expired token

Validation Errors

Causes:
  • Invalid field values
  • Missing required fields
  • Format constraints not met

Not Found Errors

Causes:
  • Invalid transaction reference
  • Resource doesn’t exist
  • Unauthorized access to resource

Payment-Specific Errors

Insufficient Balance

Invalid Mobile Number

Transaction Already Refunded

Best Practices

  1. Always check the status code first to determine the error type
  2. Log the complete error response for debugging
  3. Parse the detail field for user-friendly error messages
  4. Implement retry logic for transient errors (5xx status codes)
  5. Handle validation errors by displaying specific field errors to users