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

# Error codes and messages

> Every error code, what it means, and how to fix it.

Use the `code` field to decide what to do. Messages are shown as examples; IDs and amounts in them change.

## Request and setup

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `bad_request` | 400 | The request could not be understood. | Check your JSON is valid. |
| `api_version_required` | 400 | The API-Version header is required and must be the version set on this account. | Add the `API-Version` header. |
| `invalid_api_version` | 400 | '2026-9-22' is not a valid API version. Expected YYYY-MM-DD-name, for example 2026-10-29-atlas. | Fix the spelling. |
| `api_version_mismatch` | 400 | The API-Version '…' does not match the version set on this account ('…'). | Send the version shown in the Bridge app (**Settings → Account**). |
| `unsupported_api_version` | 400 | The requested API version '…' is not supported. | Use a supported version. |
| `api_version_sunset` | 400 | API version '…' is no longer supported. Migrate to '…'. | Move to the newer version. |
| `payload_too_large` | 413 | The request body is too large. | Keep the body under 10 KB. |
| `route_not_found` | 404 | The requested route does not exist. | Check the URL and method. |
| `rate_limit_exceeded` | 429 | Too many requests | Wait for `Retry-After`. |

## Access

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `authentication_failed` | 401 | Missing X-BRIDGE-API-Key header. | Send your API key. See all [key messages](https://docs.bridge.linkio.world/control-app/api-keys.md#key-errors). |
| `forbidden` | 403 | This IP address is not allowed to call the API. This request came from 198.51.100.7. … | Add the address to your [IP allowlist](https://docs.bridge.linkio.world/control-app/ip-allowlist.md). |
| `forbidden` | 403 | This API key does not have access to this resource. | Give the key the right [scope](https://docs.bridge.linkio.world/control-app/api-keys.md#scopes-what-a-key-can-do). |
| `forbidden` | 403 | This organization does not have access to this service. | Contact support. |
| `pair_not_enabled` | 403 | The USDC/NGN pair is not enabled for this business. Contact support to enable it before creating onramp transactions. | Turn the pair on in [Currency pairs](https://docs.bridge.linkio.world/control-app/ramp-pairs.md). |

## Fields

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `validation_failed` | 422 | Request validation failed | Read the `errors` list. Each entry names the `field` and the problem. |
| `invalid_amount` | 422 | Invalid amount 1000 NGN: minimum is 15000 | Stay within the [limits](https://docs.bridge.linkio.world/before-you-build/limits.md). |

## Customers

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `customer_not_found` | 404 | Customer cus\_… not found | Check the ID. It must belong to your business and environment. |
| `customer_banned` | 409 | Customer cus\_… is banned | Contact support. |

## Quotes

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `quote_not_found` | 404 | Quote qte\_… not found | Get a new quote. Unused quotes are deleted 10 minutes after they expire. |
| `quote_expired` | 400 | Quote qte\_… has expired | [Refresh the quote](https://docs.bridge.linkio.world/api-reference/quotes/refresh.md). |
| `quote_locked` | 409 | Quote qte\_… is locked and cannot be refreshed | The quote is already used by a payment. Get a new quote for a new payment. |

## Payments

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `payment_not_found` | 404 | Payment pay\_… not found | Check the ID. |
| `payment_already_completed` | 409 | Payment pay\_… is already completed | Nothing to do. |
| `payment_canceled` | 400 | Payment pay\_… has been canceled | Create a new payment. |
| `invalid_transition` | 400 | Invalid status transition on payment pay\_… | The payment can't move to that step from where it is. |
| `payment_processing_failed` | 422 | Failed to process payment pay\_…: … | Read the reason. Try again with a new quote. |
| `risk_review_required` | 422 | Risk review required | The payment needs a manual check. Contact support. |
| `transaction_blocked` | 422 | Transaction blocked: … | The payment was blocked by our risk checks. Contact support. |

## Retries

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `idempotency_conflict` | 409 | A request with this Idempotency-Key is already being processed. | Wait, then retry. |
| `idempotency_conflict` | 409 | This Idempotency-Key was used with a different request payload. | Use a new key for a different request. |

## Our side

| Code | Status | Example message | How to fix |
| - | - | - | - |
| `route_temporarily_unavailable` | 503 | This route temporarily unavailable | Retry later. |
| `request_timeout` | 504 | Request timed out | Retry with the same `Idempotency-Key`. |
| `database_error` | 503 | (varies) | Retry later. |
| `unexpected_error` | 500 | An unexpected error occurred. | Retry later. Contact support with the `request_id` if it continues. |


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