Esc

Quick Navigation

Overview

Dashboard home

Documentation

API Reference

Playground

Test live

API Keys

Manage credentials

Usage Stats

Analytics

Webhooks

Event endpoints

Pricing

Plans & limits

SDKs

Code examples

Error Codes

Troubleshooting

Authentication

Bearer token setup

Gift Cards API

Purchase gift cards

Airtime API

Top up mobile

Wallet API

Balance & funding

↵ select Esc close

Error Codes & Status Reference

Every API error includes a machine-readable code. Use it for programmatic handling.

Error Response Format

4xx / 5xx

{
  "status":        "error",
  "error":         {
    "code":          "INSUFFICIENT_BALANCE",
    "message":       "Wallet balance too low.",
    "http_status":   402
  }
}

Field Reference

status

Always "error" for failed requests

error.code

Machine-readable. Use this in code.

error.message

Human-readable. For debugging.

error.http_status

HTTP status code for this error.

HTTP Status Codes

200

201

Created

400

Bad Request

401

Unauthorized

402

Payment Req.

403

Forbidden

404

Not Found

409

Conflict

422

Unprocessable

429

Rate Limited

500

Server Error

503

Unavailable

Application Error Codes

Code	HTTP	Message	Cause	Fix
`INVALID_API_KEY`	401	Invalid API key	Key doesn't exist or was revoked	Check your key is correct
`MISSING_API_KEY`	401	No API key provided	Authorization header missing	Add Authorization: Bearer sk_live_...
`INSUFFICIENT_BALANCE`	402	Wallet balance too low	Not enough funds for this transaction	Fund your merchant wallet
`INVALID_PRODUCT_ID`	400	Product not found	Product ID not in catalogue	Call GET /v1/giftcard/products
`INVALID_AMOUNT`	400	Amount not valid	Zero, negative or bad denomination	Use valid denomination from product
`INVALID_PHONE_NUMBER`	400	Phone format invalid	Not in E.164 format	Format: +2348012345678
`PRODUCT_OUT_OF_STOCK`	404	No inventory	Key pool empty for this product	Contact support or try different denom
`DUPLICATE_REFERENCE`	409	Reference already used	Your ref ID was already submitted	Use unique reference per transaction
`RATE_LIMIT_EXCEEDED`	429	Too many requests	You've hit your rate limit	Implement exponential backoff
`MERCHANT_SUSPENDED`	403	Account suspended	Merchant account is disabled	Contact Iascroft support
`INVALID_CURRENCY`	400	Currency unsupported	Currency not in allowed list	GET /v1/currencies for valid codes
`WEBHOOK_INVALID_SECRET`	401	Signature mismatch	Payload doesn't match webhook secret	Check signature verification logic
`VALIDATION_FAILED`	422	Validation failed	Valid JSON but fields invalid	Check error.details for specifics
`INTERNAL_ERROR`	500	Server error	Unexpected error on our end	Retry with backoff. Contact support