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

# Errors and troubleshooting

> Understand API errors and know what to do next.

## Read an error

When a request fails, the HTTP status tells you the type of failure. The response usually includes a `code` and a message:

```json theme={null}
{
  "status": "error",
  "message": "Missing required scope.",
  "code": "MISSING_SCOPE"
}
```

Use the HTTP status and `code` in your application logic. The message explains the problem, but its wording can change. Some errors also include `details`, such as the minimum and maximum amount allowed.

Successful responses usually contain `status: "success"` and `data`. Check each endpoint for its exact response.

## Common errors

| HTTP status | Code or situation | What to do |
| - | - | - |
| `400` | `BAD_REQUEST`, `INVALID_JSON` | Check required fields, JSON formatting and amount precision. |
| `401` | `AUTH_FAILED` | Check your API key, signature and timestamp. |
| `403` | `MISSING_SCOPE`, `SERVICE_NOT_INCLUDED`, `FORBIDDEN` | Check the key's permissions and the services available to your business. |
| `404` | `NOT_FOUND` | Check the resource ID and the business you selected. |
| `404` | `RATE_NOT_FOUND` | A conversion price is unavailable for the selected currencies. Try again later. |
| `409` | `IDEMPOTENCY_CONFLICT` | Check that the retry key, body, quote ID and reference match your original request. |
| `409` | `INSUFFICIENT_BALANCE` | Check that your available source balance covers the amount and fees. |
| `409` | `INSTANT_CONVERSION_LIMIT_EXCEEDED` | Read the allowance details and check any earlier attempt before retrying. |
| `413` / `414` | Request body or URL too large | Reduce the size of the request. |
| `422` | `RATE_ROUTE_AMOUNT_OUT_OF_RANGE` | Use a source amount within the returned conversion limits. |
| `422` | Per-payment or monthly payout limit exceeded | Check your business's [limits](https://docs.ledig.io/guides/limits.md). |
| `423` | `COMPLIANCE_REVIEW_REQUIRED` | The operation or recipient needs review. Do not retry automatically or create a replacement recipient. Contact support if you need an update. |
| `429` | `RATE_LIMITED` | Slow down your requests and follow `Retry-After` when returned. |
| `500` / `503` | Temporary or unexpected failure | Wait before retrying reads. For writes, follow the [retry guide](https://docs.ledig.io/guides/idempotency.md). |
| `501` | `NOT_IMPLEMENTED` | The requested operation is not available. |

Endpoints may return additional codes. Handle unrecognised codes as errors using the HTTP status.

## Fix a missing or invalid field

A missing or invalid field usually returns `400 BAD_REQUEST`. For example, a transfer request without `quoteId` returns:

```json theme={null}
{
  "status": "error",
  "message": "quoteId is required.",
  "code": "BAD_REQUEST"
}
```

Add the missing field and check the rest of your request. A message such as `payOut.recipientId is required.` points to `recipientId` inside `payOut`.

For `POST /v1/wallets`, `400 BAD_REQUEST` with `details.reason: "unsupported_asset_network"` means the asset and network pair is not supported for a new deposit address. Select a pair from `GET /v1/wallets/options` before trying again. `503 PROVIDER_UNAVAILABLE` means setup is temporarily unavailable; follow the retry guide with the original key and body.

## Understand quote errors

These examples use fictional amounts. Read the values in your own response for the limits that apply to your business.

### No conversion price

A quote can return `404` when a price is unavailable:

```json theme={null}
{
  "status": "error",
  "message": "A price is currently unavailable for this pair. Try again later.",
  "code": "RATE_NOT_FOUND"
}
```

### Amount outside the conversion limits

A quote can return `422` when the amount you want to convert is too small or too large:

```json theme={null}
{
  "status": "error",
  "message": "The amount you convert must be between 10 and 50000 USDT for this conversion direction.",
  "code": "RATE_ROUTE_AMOUNT_OUT_OF_RANGE",
  "details": {
    "sourceCurrency": "USDT",
    "minimumAmount": "10",
    "maximumAmount": "50000"
  }
}
```

This limit applies to the **source amount** you are converting. A payout method's limit applies to the **destination amount** being sent. Business payout allowances are measured in USD equivalent. See [Limits](https://docs.ledig.io/guides/limits.md) for the difference.

### Not enough available funds

A quote can return `409` when your available source balance is too low:

```json theme={null}
{
  "status": "error",
  "message": "Available balance is not sufficient for this action.",
  "code": "INSUFFICIENT_BALANCE"
}
```

Check the amount and all fees against your available balance.

## Retry after a failure

For temporary read failures, wait before trying again and increase the delay after repeated failures.

A timeout or `5xx` response on a write does not mean the request failed. It may already have been processed. Keep the original request identifiers and use the [retry rules](https://docs.ledig.io/guides/idempotency.md) to check or recover the result before creating another payment.

## Request IDs

Every API response includes an `x-request-id` header. Save this ID when a request fails so support can locate it.

You can also send your own `x-request-id`. Use 8–128 characters containing only letters, digits, `.`, `_`, `:` or `-`. Ledig keeps a valid ID and generates one if it is missing or invalid.

When contacting support, include:

* The request ID and approximate time.
* Sandbox or Live.
* The HTTP method and endpoint, such as `GET /v1/balances/USD`.
* The HTTP status and error code.

Do not include API keys, secrets, signatures or customer documents.

## Troubleshooting checklist

1. Check that your API URL and credentials belong to the same [environment](https://docs.ledig.io/introduction.md#environments).
2. Use the current Unix timestamp in seconds and keep your server clock in sync.
3. Sign the exact method, path, query string and body you send.
4. Check the API key's required permissions.
5. If acting for a managed business, use HMAC v2 and the correct business-selection headers.
6. Contact [support@ledig.io](mailto:support@ledig.io) with the request ID if you need help.


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