---
title: "Errors"
url: https://docs.truemarkets.co/developer-resources/errors
description: "Every error returns the same body. Branch on code, fall back to type, and retry only the cases listed here."
---

Docs index: https://docs.truemarkets.co/llms.txt

# Errors

Every error returns the same JSON body. Branch on `code` when you recognize it, fall back to `type` when you don't, and handle the cases in [Handle common errors](#handle-common-errors).

## The error body

```json
{
  "type": "failed_precondition",
  "code": "quote_stale",
  "message": "quote expired before it landed; request a new quote",
  "request_id": "7b1f0c2e-5a9d-4e36-8f10-2d4c6b8a9e31"
}
```

| Field              | Meaning                                                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`             | The category of error. There is a fixed set of types, and each one maps to one HTTP status.                                                                                          |
| `code`             | The specific condition, such as `quote_stale`. We add codes over time, so handle the ones you know and fall back to `type` for the rest. Omitted when no specific condition applies. |
| `message`          | A description for people. Don't branch on it, because the wording can change.                                                                                                        |
| `request_id`       | Our id for the request. Include it when you write to support. Send your own `X-Request-Id` header and we use that instead.                                                           |
| `field_violations` | On `invalid_argument`, the fields that failed validation and why.                                                                                                                    |
| `metadata`         | Extra string values for the `code`. Which keys appear depends on the code.                                                                                                           |

## Status for each type

| `type`                | Status |
| --------------------- | ------ |
| `invalid_argument`    | 400    |
| `unauthenticated`     | 401    |
| `permission_denied`   | 403    |
| `not_found`           | 404    |
| `method_not_allowed`  | 405    |
| `conflict`            | 409    |
| `failed_precondition` | 422    |
| `resource_exhausted`  | 429    |
| `internal`            | 500    |
| `unavailable`         | 503    |

## Handle common errors

| You see                                   | Do this                                                                                                                                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`                                     | Check the token and, for a Gateway call, the `TM-On-Behalf-Of` header. Mint or refresh the token once; retrying without a change fails the same way.                        |
| `422` with `quote_stale`                  | The quote expired. Place the order again and execute right away.                                                                                                            |
| `201` with an empty `order_id`            | No order was created, and `quote.issues` says why. Usually the wallet can't fund the buy: fund it and place the order again.                                                |
| `422` with `insufficient_balance`         | The wallet can't fund a sell or perpetual order. Fund it, then place the order again.                                                                                       |
| `409` with `already_submitted` on execute | The transaction already landed. Don't resubmit; read the order.                                                                                                             |
| `429`                                     | You sent too many requests. Wait the seconds in `X-RateLimit-Reset`, then retry. Your token is still valid. [Rate limits](https://docs.truemarkets.co/developer-resources/rate-limits) has the limits. |
| `503` when you create a user              | Repeat the same request. It finishes creating the wallets.                                                                                                                  |
| `500` or `503` on other calls             | Retry with backoff. If it keeps failing, send us the `request_id`.                                                                                                          |

Next: the [API reference](https://docs.truemarkets.co/api) has the responses for each endpoint.