Errors

Error shape

When a request fails, the API returns a non-2xx status code with a JSON body:

{
  "statusCode": 400,
  "message": "Invalid currency: XYZ",
  "timestamp": "2026-08-03T10:15:00.000Z",
  "path": "/v1/api/balance/XYZ",
  "request": {
    "method": "GET",
    "url": "/v1/api/balance/XYZ"
  }
}

number

The HTTP status code, repeated in the body for convenience.

string | string[]

A human-readable description of what went wrong. For validation errors this can be an array of field-level messages.

string

ISO-8601 timestamp of when the error was generated.

string

The request path that produced the error.

Validated request bodies are checked with a whitelist — unknown fields are rejected outright with a 400 rather than silently ignored, so double-check field names against the API Reference if you get an unexpected validation error.

HTTP status codes

Status	Meaning
`200`	Request succeeded.
`201`	Resource created.
`400`	Bad request — invalid input, business-rule violation (insufficient balance, duplicate `paymentReference`, missing `rateKey`, unsupported currency), or a downstream provider error.
`401`	Missing or invalid credentials — bad `x-api-key`, or your business isn’t approved for API access.
`403`	The `x-api-key` header is missing entirely.
`404`	Route doesn’t exist.
`500`	Unexpected server error. If this persists, contact [email protected] with the `timestamp` from the error body.

Common error messages

Message	Cause	Fix
`api key header is needed to access this resources`	`x-api-key` header missing	Add the header to your request.
`Invalid api key`	Key doesn’t exist or was revoked	Generate a new key from the dashboard.
`You are not allowed to access this resource, contact support for more info [email protected]`	API access not enabled for your business	Contact support to enable `isAllowAPIAccess`.
`Transaction already exists with <reference>`	You reused a `paymentReference` on `/api/deposit`	Use a unique reference per collection attempt.
`Invalid fromCurrency: <currency>` / `Invalid currency: <currency>`	No wallet/provider configured for that currency	Check supported currencies in the Introduction.
`Invalid paymentReference`	No transaction matches the reference on `/api/transaction/:paymentReference`	Verify the reference used on `/api/deposit`.
`Rate key is required`	Payout `fromCurrency` and `toCurrency` differ but no `rateKey` was supplied	Fetch a quote first and pass its `rateKey`.
`Insufficient balance`	Payout amount exceeds your wallet balance	Fund the wallet or reduce the amount.
`Unsupported payout type`	The `fromCurrency`/`toCurrency` combination can’t be resolved to a payout route	Contact support — this combination isn’t enabled.

Idempotency

POST /api/deposit is naturally idempotent on paymentReference — retrying with the same reference returns a 400 Transaction already exists, so it’s safe to retry deposit creation requests as long as you keep the reference stable. There is currently no dedicated idempotency key for /api/payout; use your own sessionId/narration bookkeeping to avoid double-submitting payouts on retry.

Get Started

Guides

Error shape

HTTP status codes

Common error messages

Idempotency

​Error shape

​HTTP status codes

​Common error messages

​Idempotency

Error shape

HTTP status codes

Common error messages

Idempotency