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

# Errors

> One shape, everywhere — branch on the code, not the message

Every error, from every layer, has the same body:

```json theme={null}
{
	"code": "INSUFFICIENT_FUNDS",
	"message": "Account 5b6f… does not hold enough USDC_TRON to cover this transaction.",
	"details": ["amount"]
}
```

| Field | |
| - | - |
| `code` | Stable and machine-readable. **Branch on this.** |
| `message` | Human-readable, for your logs — subject to change without notice. |
| `details` | Present on validation failures: one entry per rejected field. |

## Status codes you'll see everywhere

| Status | Meaning |
| - | - |
| `400` | Malformed request, or a ledger rule refused it — `code` says which. |
| `401` | Missing, malformed, or revoked API key. |
| `403` | The key is valid but lacks the scope this operation requires. |
| `404` | No such record, or it belongs to another tenant. |
| `409` | Idempotency conflict — this key was already used with a different body. |
| `422` | `INSUFFICIENT_FUNDS` and similar: well-formed, but the ledger says no. |

## Terminal vs. retryable

> [tab] Retry these
>
> `429` (honour `Retry-After`) and any `5xx`, always with the **same**
> idempotency key. Anything else is not a transient failure.

> [tab] Don't retry these
>
> `422 INSUFFICIENT_FUNDS`, `400 UNBALANCED_TRANSACTION`, and
> `403 DESTINATION_SCREENED` are terminal — the request was understood
> and refused. Retrying changes nothing; fix the underlying condition
> first (top up, correct the amount, or use an allowed destination).


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