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

# Errors

> The error format, every error code, and what to do about each one.

Payve uses HTTP status codes and a JSON error body. Read the status first, then `error.code`.

## Error format

```json
{
  "error": {
    "code": "wallet_insufficient_funds",
    "message": "Wallet balance is insufficient for this transaction.",
    "requestId": "req_8a1c4e2f9b7d3a60",
    "details": {
      "currency": "NGN",
      "available": "120000",
      "required": "5025000"
    }
  }
}
```

**error.code** `string`

A stable, machine-readable code. Branch on this.

**error.message** `string`

A sentence for a person. The wording can change. Do not match on it.

**error.requestId** `string`

Identifies this request. Log it and quote it to support. Not present on every error.

**error.details** `object`

Extra facts for some codes, such as the fields that failed validation.

### Validation errors

A request body that fails validation returns `422` with the failing fields:

```json
{
  "error": {
    "code": "validation_missing_field",
    "message": "Validation failed",
    "details": {
      "fields": {
        "amount": ["amount must be a positive number", "amount must be an integer number"],
        "beneficiary": ["beneficiary must be an object"]
      }
    }
  }
}
```

An unknown field in the body is also a validation error.

### The short format

Some responses come straight from the web framework and have no `error.code`. Authentication failures, an unknown URL and a malformed id in a URL look like this:

```json
{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}
```

> [!NOTE]
>
> Write one error handler that copes with both formats: if `error` is an object, use `error.code`;
> if `error` is a string, use the HTTP status and the top-level `message`.

```javascript Node
async function payve(path, init) {
  const res = await fetch(`${process.env.PAYVE_API_URL}${path}`, init);
  const body = await res.json().catch(() => ({}));
  if (res.ok) return body.data;

  const structured = body.error && typeof body.error === 'object';
  const err = new Error(structured ? body.error.message : (body.message ?? res.statusText));
  err.status = res.status;
  err.code = structured ? body.error.code : null;
  err.requestId = structured ? body.error.requestId : null;
  err.details = structured ? body.error.details : null;
  throw err;
}
```

```python Python
import os, requests

class PayveError(Exception):
    def __init__(self, status, code, message, request_id=None, details=None):
        super().__init__(message)
        self.status, self.code = status, code
        self.request_id, self.details = request_id, details

def payve(method, path, **kwargs):
    res = requests.request(method, f"{os.environ['PAYVE_API_URL']}{path}", **kwargs)
    body = res.json() if res.content else {}
    if res.ok:
        return body.get("data")
    err = body.get("error")
    if isinstance(err, dict):
        raise PayveError(res.status_code, err.get("code"), err.get("message"),
                         err.get("requestId"), err.get("details"))
    raise PayveError(res.status_code, None, body.get("message", res.reason))
```

## HTTP statuses

| Status | Meaning | Retry? |
| - | - | - |
| `200` | Success. | |
| `201` | Created. | |
| `202` | Accepted. The transaction is not finished yet. | |
| `204` | Success, with no body. | |
| `400` | Bad request: a missing header or a malformed id in the URL. | No. Fix the request. |
| `401` | The key is missing, wrong, revoked or for the other environment. | No. |
| `403` | The key is valid but may not do this. | No. |
| `404` | The object does not exist on your account. | No. |
| `409` | Conflict with the current state, or a request in flight. | Only `idempotency_conflict`. |
| `422` | The request is well-formed but cannot be carried out. | No. Fix the request. |
| `429` | Too many requests. | Yes, after `Retry-After` seconds. |
| `500` | Something broke on Payve's side. | Yes, with the same idempotency key. |
| `502` | A bank or operator returned an error. | Yes, with the same idempotency key. |
| `503` | No route is available right now. | Yes, later, with the same key. |

## Error codes

The **Status** column shows the HTTP status where the code always arrives with the same one.

### Validation

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `validation_missing_field` | `422` | A field is missing, malformed or not allowed. See `details.fields`. | Fix the fields named. |
| `validation_invalid_amount` | | The amount is not acceptable. | Send a positive whole number in minor units. |
| `validation_invalid_currency` | | The currency is not supported. | Use a currency from [Coverage](/essentials/coverage.md). |
| `validation_invalid_beneficiary` | `422` | The recipient details are wrong, such as an NGN account number that is not 10 digits. | Correct the details and run a [name check](/guides/name-check.md). |
| `validation_idempotency_key_required` | `400` | This endpoint needs an `Idempotency-Key` header. | Send one. |
| `validation_idempotency_key_invalid` | `400` | The key is longer than 255 characters. | Send a shorter key. |
| `validation_invalid_bvn` | | A BVN failed validation during verification. | Check the number. |
| `validation_invalid_nin` | | A NIN failed validation during verification. | Check the number. |
| `validation_invalid_rc` | | A company registration number failed validation. | Check the number. |
| `validation_invalid_tin` | | A tax identification number failed validation. | Check the number. |

`validation_missing_field` is also the code on a few `400` responses that have no more specific code. Read the `message` and `details.code`.

### Idempotency

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `idempotency_conflict` | `409` | A request with this key is still running. | Wait, then retry with the same key. |
| `idempotency_key_reused` | `422` | This key was already used on another endpoint or with another body. | Do not retry. See [Idempotency](/essentials/idempotency.md). |
| `idempotency_replay` | | Reserved. A replay returns the stored response, not this code. | |

### Wallets

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `wallet_insufficient_funds` | `422` | The wallet cannot cover the amount plus the fee. `details` shows `available` and `required`. | Fund the wallet, or send less. |
| `wallet_frozen` | `422` | The wallet is frozen. | Contact [support](/support.md). |
| `wallet_not_found` | | You have no wallet in that currency. | Create it with `POST /v1/wallets`. |
| `wallet_currency_not_enabled` | | That currency is not enabled for you. | Contact [support](/support.md). |
| `wallet_closed` | | The wallet is closed. | Contact [support](/support.md). |

### Quotes

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `quote_expired` | `422` | The quote's hold time has passed. | Request a new quote. |
| `quote_already_consumed` | `409` | The quote was already used by a transaction. | Request a new quote. |
| `quote_not_found` | | No such quote. | Check the id. |

### Resources

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `resource_not_found` | `404` | The object does not exist, or is not yours. Also returned when no exchange rate exists for a currency pair. | Check the id, or the pair. |
| `resource_conflict` | `409` | The action conflicts with the object's current state. | Fetch the object and read its status. |
| `resource_invalid_state` | `409` | The object is not in a state that allows this. `details.currentState` says which. | Fetch the object. Do not retry unchanged. |

### Channels

A channel is the bank or operator connection that carries a payment.

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `no_eligible_channel` | `503` | No route can carry this transaction right now. | Retry later with the same idempotency key. |
| `channel_unavailable` | | The route is down, or cannot do what was asked. | Retry later. |
| `channel_unknown_error` | `502` | The bank or operator returned an error. | Read the `message`. Retry with the same key. |
| `channel_timeout` | | The bank or operator did not answer in time. | Check the transaction status before retrying. |
| `channel_beneficiary_bank_down` | | The recipient's bank is offline. | Retry later. |
| `channel_insufficient_balance` | | The route cannot fund this payment right now. | Retry later, or contact [support](/support.md). |
| `channel_auth_failed` | | Payve could not authenticate with the provider. | Contact [support](/support.md). |

### Authentication and permission

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `unauthorized` | `401` | No valid credential. | See [Authentication](/get-started/authentication.md). |
| `forbidden` | `403` | The key may not do this. `details.code` may give the reason. | Check the key's scopes. |
| `step_up_required` | `403` | A dashboard session needs a fresh authenticator code. API keys do not get this. | |
| `invalid_credentials` | | Dashboard sign-in failed. | |
| `token_expired` | | A dashboard session token expired. | |
| `session_expired` | | A dashboard session ended. | |
| `totp_required` | | Dashboard sign-in needs an authenticator code. | |
| `totp_invalid` | | The authenticator code was wrong. | |

### Compliance and limits

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `kyc_tier_insufficient` | `403` | Your business is not verified to the level this needs. | Finish verification in the dashboard. |
| `merchant_suspended` | `403` | Your account is suspended. | Contact [support](/support.md). |
| `merchant_limit_exceeded` | `422` | The amount is over a limit. `details.limitType` says which. | Send less, or ask support about your limits. |
| `fraud_blocked` | `422` | Blocked by fraud monitoring. | Do not retry. Contact [support](/support.md). |
| `sanctions_blocked` | `403` | A party matches a sanctions list. | Do not retry. Contact [support](/support.md). |
| `identifier_blocked` | `403` | The account cannot be used. | Contact [support](/support.md). |
| `compliance_hold` | `202` | Held for a compliance review. | Wait for the outcome. |

### Rate limiting and server errors

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `rate_limit_exceeded` | `429` | Too many requests. | Wait for `Retry-After` seconds. See [Rate limits](/essentials/rate-limits.md). |
| `internal_error` | `500` | An unexpected error at Payve. | Retry with the same idempotency key. If it persists, send support the `requestId`. |

## Payouts that fail later

A payout can be accepted with `202` and fail afterwards, for example when the recipient's bank rejects it. That is not an HTTP error. You learn of it from the `payout.failed` webhook or from `GET /v1/payouts/{id}`, where `userMessage` gives the reason in plain words.

## Cautions

> [!WARNING]
>
> Never retry a money call with a **new** idempotency key because you got an error you did not
> understand. Look up the transaction first. A `500` or a timeout does not prove nothing happened.

> [!TIP]
>
> Log `error.code`, `error.requestId`, the HTTP status and your `Idempotency-Key` for every failed
> call, and quote them when you contact support.
