Skip to main content

​
Error Response Format

All errors follow the RFC 7807 Problem Details specification: 
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Detailed error message",
  "instance": "/Gateway/v1/Payment/initiate-checkout"
}

​
HTTP Status Codes

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

​
Common Error Scenarios

​
Authentication Errors

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing authentication token"
}
Causes:
  • Missing Authorization header
  • Invalid API key
  • Expired token

​
Validation Errors

{
  "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Amount must be greater than 10"
}
Causes:
  • Invalid field values
  • Missing required fields
  • Format constraints not met

​
Not Found Errors

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Transaction not found"
}
Causes:
  • Invalid transaction reference
  • Resource doesn’t exist
  • Unauthorized access to resource

​
Payment-Specific Errors

​
Insufficient Balance

{
  "status": 422,
  "detail": "Insufficient balance in wallet"
}

​
Invalid Mobile Number

{
  "status": 400,
  "detail": "Invalid mobile number format"
}

​
Transaction Already Refunded

{
  "status": 422,
  "detail": "Transaction has already been fully 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