Error Handling

The API uses standard HTTP status codes and returns JSON error responses.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	IP or origin not whitelisted for your API token
422	Unprocessable Entity	Validation error or business logic failure
429	Too Many Requests	Rate limit exceeded (30 requests/minute on transaction endpoints)
500	Internal Server Error	Something went wrong on our end

Error Response Format

All validation and business logic errors return HTTP 422 with this structure:

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "Specific error message for this field"
    ]
  }
}

Validation Errors (422)

When a request fails field validation, the response includes field-level error details:

{
  "message": "The given data was invalid.",
  "errors": {
    "mobile_number": ["The mobile number field is required."],
    "network": ["The network field is required."],
    "plan": ["The selected plan is invalid."]
  }
}

Business Logic Errors (422)

Errors from business rules (insufficient balance, spending limits, account restrictions) are also returned as 422 with the error under a status or amount field:

Insufficient Balance

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["Insufficient wallet balance!"]
  }
}

Service Unavailable

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Service unavailable!."]
  }
}

Account Restricted (KYC)

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Your account has been restricted for transaction, Please submit your KYC to activate your account or contact support!."]
  }
}

Negative Wallet Balance

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Your account has been temporarily restricted due to a negative wallet balance. Please contact support for assistance."]
  }
}

Maximum Wallet Balance Exceeded

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Your account has been restricted because your wallet balance exceeds the limit for your KYC tier. Please upgrade your KYC or contact support to continue using your account."]
  }
}

Daily Spending Limit Exceeded

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Sorry, your daily data spending limit exceeded! Limit: ₦50,000.00"],
    "current_spent": [42000],
    "daily_limit": [50000],
    "service_type": ["data"]
  }
}

The service_type will match the endpoint — airtime, data, cable_subscription, bill_payment, or result_checker.

Provider Failure

When a transaction is processed but fails at the provider level:

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Something Went Wrong! Try again Letter"]
  }
}

KYC Tier Not Found

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["No KYC tier found for your verification level!"]
  }
}

IP Whitelist Error (403)

If your IP or request origin is not whitelisted for your API token:

{
  "status": false,
  "message": "Access Denied: Your IP (192.168.1.1) or Origin is not whitelisted for this API token."
}

Rate Limiting (429)

Transaction endpoints are rate-limited to 30 requests per minute. If you exceed this limit, you'll receive a 429 response. Wait for the duration indicated in the Retry-After header before making additional requests.

Common Error Messages Reference

Error Message	HTTP Code	Cause
"Insufficient wallet balance!"	422	Not enough funds in wallet
"Service unavailable!."	422	Service is disabled
"Your account has been restricted for transaction..."	422	KYC restriction
"Sorry, your daily {service} spending limit exceeded!"	422	Spending limit reached
"Your account has been temporarily restricted..."	422	Negative wallet balance
"Something Went Wrong! Try again Letter"	422	Provider failure
"No KYC tier found..."	422	KYC tier missing
"Access Denied: Your IP..."	403	IP not whitelisted
"Unauthenticated."	401	Invalid or missing token

Best Practices

• Always check the HTTP status code before parsing the response body
• Handle both status and amount error fields in your error parsing
• Log error responses for debugging
• Implement exponential backoff for 429 and 5xx errors
• Validate inputs client-side before sending requests to reduce 422 errors