Error Codes

All API errors follow a consistent format:

{
  "error": {
    "code": "insufficient_funds",
    "message": "The customer's mobile money account has insufficient funds.",
    "type": "payment_error",
    "param": null
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad request — invalid parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — insufficient scopes
404	Not found
409	Conflict — idempotency conflict
429	Too many requests — rate limit exceeded
500	Internal server error

Payment Errors

Code	Description
insufficient_funds	Customer doesn't have enough balance
payment_timeout	Customer didn't confirm in time
provider_unavailable	Payment provider is temporarily unavailable
invalid_phone	Phone number format is invalid
invalid_operator	Unsupported mobile money operator
card_declined	Card was declined
expired_card	Card has expired
incorrect_cvc	CVC code is incorrect
processing_error	Generic processing error

Validation Errors

Code	Description
invalid_amount	Amount is below minimum or above maximum
invalid_currency	Currency is not supported
missing_required_field	A required field is missing
invalid_parameter	A parameter has an invalid value

Authentication Errors

Code	Description
invalid_api_key	API key is invalid or revoked
expired_api_key	API key has expired
insufficient_scopes	API key doesn't have the required scopes
ip_not_allowed	Request IP is not in the key's whitelist