Errors - One Pay

Every error looks the same:

{
  "error": {
    "code": "insufficient_funds",
    "message": "not enough available balance: this payout needs 9225000 XAF (amount plus fee), 4575 is available",
    "request_id": "req_6b372c76b6baa259e41b97e3"
  }
}

code never changes: build your handling on it.
message is for people and may be reworded.
request_id identifies the request: quote it when you contact One Pay.

By status

HTTP	Meaning	Examples of `code`	Retry?
400	The request is wrong	`invalid_request`, `amount_too_small`	No: fix it
401	Missing or wrong API key	`api_key_missing`, `api_key_invalid`, `api_key_revoked`	No
403	Not allowed	`merchant_suspended`, `merchant_not_active`, `test_mode_only`	No
404	It does not exist (for this key)	`payin_not_found`, `payout_not_found`	No
409	Conflicts with what already happened	`idempotency_conflict`, `idempotency_in_progress`, `recipient_not_approved`	Only `idempotency_in_progress`
422	Valid, but cannot be done	`insufficient_funds`, `limit_exceeded`	No
429	Too many requests	`rate_limited`	Yes, after a pause
500	Our fault	`internal_error`	Yes, with the same idempotency key
503	Temporarily unavailable	`service_unavailable`, `provider_unavailable`	Yes, later

A 400 names the field that is wrong:

{
  "error": {
    "code": "invalid_request",
    "message": "customer.phone: must be a Cameroon mobile number like +237650000000",
    "request_id": "req_0285ce59e59a0dd8e1f70632"
  }
}

Payments that fail

A payment the partner refuses is not an API error: the request succeeds and the payin or payout ends with status: "failed" and a failure:

"failure": {
  "code": "insufficient_funds",
  "message": "The customer did not have enough money"
}

You also receive a payin.failed or payout.failed webhook.