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

# Handle errors

> Branch on the error code, decide whether to fix, retry or resend, back off between retries, and log what you'll need to report a problem.

Every error has the same shape, and your code decides what to do from `error.code`. For each error, you do one of three things: fix the request, send the same request again with the same key, or send a new request with a new key.

## 1. Log the request ID

Every response from the API carries an `x-request-id` header, errors and successes alike. The exception is a request too malformed for the API to read, such as one with oversized headers, which our web server answers before the API sees it. Log it with your own record of the request. It's the first thing we ask for when you [report a problem](/support#report-a-problem).

## 2. Branch on the code

Read `error.code`, never `message`: `message` is written for people and can change. `type` groups codes into categories. The [error reference](/errors) lists every code with its status and type.

Three fields add detail when they apply:

| Field                                | When it's there                                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `param`                              | The error concerns one field of your request. It names the field, never its value.            |
| `reject_reason`                      | The broker or the exchange refused an order, an application or an allocation. It says why.    |
| `order`, `application`, `allocation` | The error concerns one of your orders, applications or allocations. The field holds its `id`. |

## 3. Decide: fix, retry or resend

What decides it is whether we stored your request. The [idempotency page](/idempotency#when-to-use-a-new-key) says, code by code, whether we did and what to do.

When a response carries a `Retry-After` header, wait that many seconds before you send the request again.

<Warning>
  After a timeout or a `5xx`, send the same request with the same key, unless the code tells you to use a new one. A new key is a new request, and for an order that means a second order at the exchange.
</Warning>

## 4. Back off between retries

A `5xx` without a `Retry-After` header doesn't say how long to wait, so back off:

1. Wait 1 second before the first retry.
2. Double the wait after each failure, and add a random jitter to it, so your retries don't arrive in step with other clients'.
3. Wait no more than 60 seconds between attempts.
4. After about 5 minutes of failures, stop. Establish the outcome of the request before you do anything else: retrieve the object if you have its `id`, or list by your `client_reference`. If the outcome is still unclear, [report the problem](/support#report-a-problem).

For a request that takes an `Idempotency-Key`, every retry uses the same key, so however many times you retry, the request is done once.

## 5. Keep a default for unrecognised codes

We can add codes to `v1` (see [Versioning](/versioning)), so give every status a safe default:

| Status          | Default for an unknown code                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `409`           | Don't send it with a new key. Retrieve the object the error's `order`, `application` or `allocation` names, if there is one. |
| `429`           | Wait `Retry-After` seconds, then send the same request with the same key.                                                    |
| Any other `4xx` | Don't send it again as it is. Log it, with its `x-request-id`.                                                               |
| `5xx`           | Send the same request again with the same key, [backing off](#4-back-off-between-retries) between attempts.                  |

For what a specific error means on your screen, see [Troubleshooting](/troubleshooting).