Errors

Every error has the same shape and an HTTP status that tells you what kind it is:

{
  "error": {
    "type": "invalid_request_error",
    "code": "phone_invalid",
    "message": "`phone` is not a valid CM mobile number.",
    "param": "phone"
  }
}

HTTP	`type`	What to do
400	`invalid_request_error`	Fix the request. `param` names the field.
401	`authentication_error`	Missing, wrong or revoked key.
403	`permission_error`	Wrong kind of key (`pk_` where `sk_` is needed), live mode not enabled, or account suspended.
404	`not_found_error`	No such object, or it belongs to the other mode (test/live).
409	`idempotency_error`	Idempotency key reused with another body, or still in use.
415	`invalid_request_error`	Send `Content-Type: application/json`.
429	`rate_limit_error`	More than 120 requests a minute on one key. Back off and retry.
500	`api_error`	Our fault. Retry with the same `Idempotency-Key`.

Common codes

`code`	Meaning
`parameter_missing` / `parameter_invalid`	See `param`.
`amount_invalid`	FCFA amounts must be multiples of 5.
`amount_out_of_range`	Below the operator's minimum or above its maximum.
`amount_too_small`	The amount does not cover the fees.
`currency_not_supported`	The operator does not take that currency.
`operator_required`	Pass `operator` (only Cameroonian numbers are detected automatically).
`operator_not_supported` / `operator_unavailable`	Unknown operator, or temporarily switched off.
`phone_invalid`	Not a valid number for the operator's country.
`balance_insufficient`	Your available balance does not cover the payout.
`live_not_enabled`	Finish verification first.
`idempotency_key_reused`	Same key, different body. Use a new key.

Payment failures (the customer declined, no money…) are not API errors: the payment is created and ends as failed with a failure.code. See Payments.