> ## 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.

# How errors look

> Every error has the same shape, so your code can handle them all the same way.

When a request works, you get a `2xx` status code. When it doesn't, you get a `4xx` or `5xx` code and an `error` object that explains what went wrong.

## The error object

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Request validation failed",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 422,
    "errors": [
      { "field": "source_amount", "message": "source_amount must be a positive decimal string" }
    ]
  }
}
```

| Field | What it means | Always there? |
| - | - | - |
| `type` | The group the error belongs to, for example `validation_error`. Use it for broad handling. | Yes |
| `code` | The exact error, for example `quote_expired`. Use it for specific handling. | Yes |
| `message` | A sentence a person can read. It may change, so don't write code that depends on it. | Yes |
| `request_id` | The ID of your request. Send it to support if you need help. | Yes |
| `status` | The HTTP status code, repeated here for convenience. | Yes |
| `errors` | For field problems: a list of each `field` and its `message`. Nested fields use dots, for example `payment_details.details.address`. | Only for field problems |
| `param` | The single field the error is about. | Sometimes |

Some errors add extra fields to help you, such as `requested_version` and `supported_versions` on [version errors](https://docs.bridge.linkio.world/before-you-build/api-versions.md#version-errors).

> [!NOTE]
>
> [Idempotency errors](https://docs.bridge.linkio.world/before-you-build/safe-requests.md#retry-safely-with-an-idempotency-key) are the one exception: they only have `code` and `message`.

## How to handle errors

**1. Check the status code**

`4xx` means something about the request needs to change. `5xx` means a problem on our side or with a partner, and trying again later may work. See [Status codes](https://docs.bridge.linkio.world/errors/status-codes.md).

**2. Check the code**

Handle the codes you expect, such as `quote_expired`. See [Error codes](https://docs.bridge.linkio.world/errors/codes.md).

**3. Show or log the message**

If it's a field problem, read `errors` to see exactly which fields to fix.

**4. Log the request ID**

Always log `request_id`. Support can find your request with it.

## Should I retry?

| Status | Retry? |
| - | - |
| `400`, `401`, `403`, `404`, `409`, `413`, `422` | No. Fix the request first. |
| `429` | Yes, after the number of seconds in the `Retry-After` header. |
| `500`, `503`, `504` | Yes, after a short wait. Use the same `Idempotency-Key` so nothing is created twice. |


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