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

# Errors

> HTTP status codes follow REST conventions. Every error body is the same shape.

## Error envelope

```json theme={null}
{
  "ok": false,
  "request_id": "01J9F5Z4X7Y3K2B1Q0M8N7V6T5",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient available balance. Available: 5.00 USDT"
  }
}
```

* `request_id` — include this when contacting support
* `error.code` — machine-readable; safe to switch on
* `error.message` — human-readable; do not parse

## HTTP status codes

| Status        | Meaning                                       | Typical codes                     |
| ------------- | --------------------------------------------- | --------------------------------- |
| `200` / `201` | Success                                       | —                                 |
| `400`         | Bad request — fix the request and retry       | `validation_error`, `bad_request` |
| `401`         | Authentication failed                         | `unauthorized`, `jwt_expired`     |
| `403`         | Authenticated but not allowed                 | `forbidden`, `account_suspended`  |
| `404`         | Resource not found                            | `not_found`, `no_route`           |
| `409`         | State conflict                                | `wallet_frozen`                   |
| `413`         | Request body too large (>64 KB)               | `bad_request`                     |
| `422`         | Business rule rejection — retry will not help | see below                         |
| `429`         | Rate limit hit; wait and retry                | `rate_limited`                    |
| `500`         | Our problem; safe to retry with backoff       | `internal_error`                  |

## 422 — business rule codes

These represent rules the request violated, not syntax errors.

| Code                     | Trigger                                                               |
| ------------------------ | --------------------------------------------------------------------- |
| `insufficient_funds`     | Wallet balance is too low to cover the transaction amount             |
| `daily_limit_exceeded`   | Today's send volume would exceed your daily cap                       |
| `monthly_limit_exceeded` | This month's send volume would exceed your monthly cap                |
| `fee_exceeds_amount`     | The fee exceeds the send amount — try a larger amount                 |
| `rate_moved`             | Exchange rate moved more than 0.5% since the quote was issued — retry |
| `screening_failed`       | Recipient failed sanctions screening                                  |

## Retrying

| Status            | Retry?                                               |
| ----------------- | ---------------------------------------------------- |
| `5xx`, `429`      | Yes, with exponential backoff (start at 1s, max 60s) |
| `401 jwt_expired` | Re-login and retry once                              |
| All other `4xx`   | No — fix the request first                           |

Use `idempotency_key` on `sendPayoutRequest` so a retry after a network error does not accidentally create a duplicate transaction.