> For the complete documentation index, see [llms.txt](https://tron-energy-doc.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tron-energy-doc.crypto-chief.com/getting-started/errors.md).

# Errors

## Errors

Every failure comes back in one shape:

```json
{
  "ok": false,
  "error": "NOT_WORTH_RENTING",
  "msg": "renting is not cheaper than burning TRX right now, so we are not selling it to you"
}
```

Branch on `error`. `msg` is written for a human reading a log and may be reworded.

### Unknown fields are refused

A field we do not recognise is a `400`, not a shrug — and the response names it, and often what you probably meant:

```json
{
  "ok": false,
  "error": "UNKNOWN_FIELD",
  "field": "address",
  "did_you_mean": "receive_address",
  "msg": "\"address\" is not a field of this request; did you mean \"receive_address\"?"
}
```

### Full list

#### Authentication

| Status | Code               | Meaning                          |
| ------ | ------------------ | -------------------------------- |
| `401`  | `UNAUTHORIZED`     | No key, or not recognised        |
| `403`  | `PROJECT_FROZEN`   | Valid key, frozen project        |
| `503`  | `AUTH_UNAVAILABLE` | Could not verify the key — retry |

#### Request

| Status | Code                       | Meaning                                                                    |
| ------ | -------------------------- | -------------------------------------------------------------------------- |
| `400`  | `UNKNOWN_FIELD`            | A field we do not recognise; see `field`                                   |
| `400`  | `INVALID_JSON`             | The body is not valid JSON for this request                                |
| `400`  | `EMPTY_BODY`               | A JSON body is required                                                    |
| `400`  | `INVALID_REQUEST`          | A value is unusable; `msg` says which                                      |
| `400`  | `IDEMPOTENCY_KEY_REQUIRED` | No `Idempotency-Key` on an order                                           |
| `413`  | `BODY_TOO_LARGE`           | Over 64 KB                                                                 |
| `429`  | `TOO_MANY_REQUESTS`        | Too many **quotes**. Orders are not throttled; `Retry-After` says how long |

#### Pricing and purchase

| Status | Code                     | Meaning                                                         | Safe to retry                                     |
| ------ | ------------------------ | --------------------------------------------------------------- | ------------------------------------------------- |
| `402`  | `INSUFFICIENT_CREDITS`   | Your balance will not cover it. Nothing bought, nothing charged | After topping up                                  |
| `409`  | `NOT_WORTH_RENTING`      | Renting is not cheaper than burning right now                   | Later — the market moves                          |
| `409`  | `ADDRESS_NOT_ACTIVATED`  | The recipient is not activated on chain                         | After [activating it](/api-reference/activate.md) |
| `409`  | `QUOTE_EXPIRED`          | That price has lapsed                                           | Yes, with a fresh quote                           |
| `409`  | `QUOTE_ALREADY_USED`     | That quote was spent by another order                           | Yes, with a fresh quote                           |
| `404`  | `QUOTE_NOT_FOUND`        | No such quote                                                   | —                                                 |
| `502`  | `NO_PRICE`               | No supplier could price it                                      | Yes                                               |
| `503`  | `NO_RATE`                | We cannot price this in your currency, so we will not guess     | Yes                                               |
| `503`  | `BILLING_UNAVAILABLE`    | Billing unreachable, so nothing is bought                       | Yes                                               |
| `503`  | `BALANCE_UNAVAILABLE`    | We could not read your balance just now                         | Yes                                               |
| `502`  | `SIMULATION_FAILED`      | The node could not simulate the call                            | Yes                                               |
| `503`  | `SIMULATION_UNAVAILABLE` | Simulation is not available on this deployment                  | —                                                 |
| `503`  | `ACTIVATION_UNAVAILABLE` | Activation is not available on this deployment                  | —                                                 |
| `500`  | `INTERNAL`               | Something failed on our side                                    | Yes, with backoff                                 |

#### Orders

| Status | Code              | Meaning                                             | Safe to retry     |
| ------ | ----------------- | --------------------------------------------------- | ----------------- |
| `404`  | `NOT_FOUND`       | No order with that key on your project              | —                 |
| `409`  | `NEEDS_ATTENTION` | Unresolved — the energy **may** have been delivered | **No.** See below |

### `NEEDS_ATTENTION` is the one that matters

Every other error above tells you nothing was bought. This one tells you we do not know.

An order goes `unresolved` when a supplier was called and the outcome never came back. Retrying is how one transfer gets paid for twice, so the order is held open, flagged for a person, and the API refuses to pretend otherwise. Read [Idempotency and Retries](/getting-started/idempotency.md) before writing your retry loop.

### Refusals are not failures

Two responses are us declining a sale rather than something going wrong:

* **`NOT_WORTH_RENTING`** — the energy market has moved far enough that renting would cost you more than burning TRX. Selling anyway would be taking money to leave you no better off.
* **`ADDRESS_NOT_ACTIVATED`** — energy cannot be delegated to an account the chain has not seen. Caught before you are charged, rather than sold as a delivery that cannot happen.

Handle both as "fall back to burning TRX this time", not as an outage.