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

# Errors and limits

> Error format, codes, request IDs and rate limits.

## Error format

Errors use standard HTTP status codes and a JSON body:

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "the account does not have enough available"
  }
}
```

**Branch on `code`, not `message`.** Messages are written for people and can change.

## Codes

| Status | Code | What to do |
| - | - | - |
| `400` | `VALIDATION` | A field is missing or malformed. Fix the request. |
| `400` | `IDEMPOTENCY_KEY_REQUIRED` | Add an `Idempotency-Key` header. |
| `401` | `UNAUTHENTICATED` | Get a new access token. |
| `402` | `INSUFFICIENT_FUNDS` | Not enough available balance. Top up or send less. |
| `403` | `INSUFFICIENT_SCOPE` | Add the named scope to your OAuth client. |
| `403` | `ENVIRONMENT_MISMATCH` | Don't name an environment other than the key's. |
| `403` | `ENVIRONMENT_UNAVAILABLE` | Live mode needs an approved account. |
| `403` | `BLOCKED` | Compliance screening refused the payment. Don't retry. |
| `403` | `FORBIDDEN` | The operation is dashboard-only. |
| `404` | `NOT_FOUND` | It doesn't exist or isn't yours. Both look the same. |
| `409` | `NOT_VERIFIED` | Finish verifying your account first. |
| `409` | `REVIEW` | The payment needs a manual compliance review. Nothing was sent. |
| `409` | `QUOTE_UNUSABLE` | The quote expired or was used. Get a new one. |
| `409` | `PROFILE_INCOMPLETE` | Complete your business details before invoicing. |
| `409` | `IDEMPOTENCY_IN_PROGRESS` | The first request with this key is still running. Retry shortly. |
| `422` | `UNSUPPORTED` | It can't work as asked (currency, corridor, account). Read `message`. |
| `422` | `UNSUPPORTED_CURRENCY` | Accounts can't be opened in this currency. |
| `422` | `REJECTED` | The payment network rejected the recipient's details. Fix them; an unchanged retry fails again. |
| `422` | `IDEMPOTENCY_KEY_REUSED` | You reused a key for a different request. |
| `429` | `RATE_LIMITED` | Wait `Retry-After` seconds. |
| `500` | `MISCONFIGURED` | Our problem. Contact us with the request ID. |
| `502` | `UPSTREAM_ERROR` | Retry; contact us if it persists. |
| `503` | `UPSTREAM_UNAVAILABLE` | Temporarily unavailable. Retry with backoff. |

Each operation in the [API reference](https://docs.talescria.com/api-reference/introduction.md) lists the codes it can return.

## Request IDs

Every response has an `x-request-id` header, such as `req_3f9c…`. Log it. If something looks wrong, send us the request ID and we can find exactly what happened.

## Rate limits

Limits apply per OAuth client, with separate budgets for reads and writes:

| | Burst | Sustained |
| - | - | - |
| Reads (`GET`) | 100 requests | 20 per second |
| Writes | 25 requests | 5 per second |

Every response includes `RateLimit-Limit` and `RateLimit-Remaining`. Over the limit, you get `429 RATE_LIMITED` with a `Retry-After` header in seconds. Wait that long, then retry with the same idempotency key.

## Retrying

| Response | Retry? |
| - | - |
| Network error or timeout | Yes, with the same idempotency key. |
| `409 IDEMPOTENCY_IN_PROGRESS`, `429`, `502`, `503` | Yes, after a delay. Use `Retry-After` when present, otherwise exponential backoff. |
| Other `4xx` | No. Fix the request or the account first. |
| `500` | Contact us with the request ID. |


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