Error Handling

Error Response Format

All errors return a consistent JSON structure with an appropriate HTTP status code.

Standard Error Response

{
  "error": "Detailed error message"
}

Authentication Error Response

{
  "message": "Authentication error message"
}

HTTP Status Codes

Code	Name	Description
`200`	OK	Request succeeded
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Valid authentication but insufficient permissions
`404`	Not Found	Requested resource not found
`409`	Conflict	Request conflicts with current state (e.g., duplicate reference)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error - retry with exponential backoff
`503`	Service Unavailable	Service temporarily unavailable

Common Error Messages

Authentication Errors

Error Message	Cause	Solution
`Invalid token`	API key is malformed or incorrect	Check API key format and value
`Expired token`	API key has expired	Generate new API key in dashboard
`Authorization header required`	Missing Authorization header	Include Authorization header in request
`Session not found`	Session has expired or is invalid	Re-authenticate with valid API key

Validation Errors

Error Message	Cause	Solution
`Invalid request body`	Malformed JSON in request body	Validate JSON syntax
`Amount must be greater than 0`	Zero or negative amount	Ensure amount is positive
`Reference is required`	Missing reference field	Include unique reference
`Account number is required`	Missing account number	Provide account number
`Bank slug is required`	Missing bank slug	Provide valid bank slug
`Duplicate reference`	Reference already exists	Use unique reference

Resource Errors

Error Message	Cause	Solution
`Bank not found`	Invalid bank slug	Use valid bank slug from List Banks
`Transfer not found`	Invalid transfer reference	Check reference is correct
`Account not found`	Account doesn't exist	Verify account details

Error Handling Best Practices

1. Implement Retry Logic

For server errors (5xx status codes), implement exponential backoff retry logic.

2. Parse Error Responses

Always check response status and extract error messages from the response body.

3. User-Friendly Messages

Map technical error messages to user-friendly ones:

"Invalid token" → "Please log in again"
"Amount must be greater than 0" → "Please enter a valid amount"
"Bank not found" → "Please select a valid bank"

4. Logging

Log errors with context including:

Timestamp
Request details
Error message and status code

Rate Limiting

Headers

Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when limit resets
`Retry-After`	Seconds to wait before retrying (429 responses)

Handling Rate Limits

When you receive a 429 status code:

Check the Retry-After header for wait time
Implement exponential backoff for subsequent requests
Consider reducing request frequency

Webhook Errors

Webhook Retry Policy

Failed webhook deliveries are retried with exponential backoff:

Attempt 1: Immediate
Attempt 2: 1 minute
Attempt 3: 5 minutes
Attempt 4: 30 minutes
Attempt 5: 2 hours
Attempt 6: 12 hours

Webhook Error Response

Your webhook endpoint should return appropriate status codes:

200 - Successfully processed
401 - Invalid signature (won't retry)
500 - Temporary error (will retry)

Testing Error Scenarios

Test Card Numbers

Use these test account numbers to simulate errors:

Account Number	Bank Slug	Error Type
`9999999999`	any	Account not found
`8888888888`	any	Invalid account
`7777777777`	any	Transfer failure
`6666666666`	any	Network timeout

Test References

Reference Pattern	Behavior
`FAIL-*`	Always fails
`TIMEOUT-*`	Times out after 30 seconds
`DUPLICATE-001`	Always returns duplicate error

Error Recovery

Use unique references for transfers to ensure requests can be safely retried without creating duplicates.

Getting Help

If you encounter persistent errors:

Check the API Status Page
Review your implementation against this guide
Contact support with:
- Your merchant ID
- Request ID from error response
- Full error details
- Steps to reproduce

Email: [email protected]