> ## Documentation Index
> Fetch the complete documentation index at: https://pay.onemarketc.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> One shape for every error, with a stable code to act on.

Every error looks the same:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`:

```json theme={null}
"failure": {
  "code": "insufficient_funds",
  "message": "The customer did not have enough money"
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.