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

# Errors

The error format, every code, and whether to retry.

Every error from the Energy Rental API uses one JSON body and one of the codes below. The Retry? column says whether sending the same request again can succeed. Each endpoint page also lists the errors it can return; see the [API reference](https://docs.luganodes.com/tron-energy/energy-rental-api.md).

## Error format

All errors return the following JSON body. Sample IDs, addresses and hashes are illustrative.

```json
{
  "status": 409,
  "code": "ACTIVE_RENTAL_EXISTS",
  "message": "This address already has a rental in progress.",
  "details": { "rental_id": "rnt_01J9X5...", "status": "pending" },
  "request_id": "req_01JA2..."
}
```

| Field        | Type    | Description                              |
| ------------ | ------- | ---------------------------------------- |
| `status`     | integer | HTTP status code                         |
| `code`       | string  | Error code from the table below          |
| `message`    | string  | Readable description                     |
| `details`    | object  | Extra context for the error              |
| `request_id` | string  | Share it with us when reporting an issue |

## Read a response

1. Check the HTTP status. `200`, `201` and `202` are successful responses. A `202` means the request was accepted and is not finished.
2. For any other status, read `code` in the JSON body and find it in the table below. Branch on `code`, not on `message`. New error codes can be added without a version change, so keep a default branch for codes you do not recognise.
3. Log `request_id` and share it with us when you report an issue.

## Error codes

| HTTP | Code                     | When                                                                                                                                                      | Action                                                                                                                                         | Retry?                   |
| ---- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| 400  | `INVALID_REQUEST`        | Malformed JSON, missing field or wrong type                                                                                                               | Fix the request                                                                                                                                | No                       |
| 400  | `INVALID_ADDRESS`        | Address format or checksum is invalid                                                                                                                     | Fix the address                                                                                                                                | No                       |
| 400  | `INVALID_AMOUNT`         | Amount is not a positive whole number in the smallest unit                                                                                                | Fix the amount                                                                                                                                 | No                       |
| 400  | `INVALID_DURATION`       | `max_wait_seconds` is out of range                                                                                                                        | Fix the value                                                                                                                                  | No                       |
| 400  | `UNSUPPORTED_TOKEN`      | Token other than USDT                                                                                                                                     | Use USDT                                                                                                                                       | No                       |
| 401  | `UNAUTHORIZED`           | Invalid API key, signature or timestamp                                                                                                                   | Check your credentials and server clock                                                                                                        | After a fix              |
| 403  | `ADDRESS_BLOCKED`        | An address matched a sanctions list                                                                                                                       | Stop the transfer. Contact us if you believe the match is wrong                                                                                | No                       |
| 404  | `NOT_FOUND`              | Unknown endpoint or rental ID                                                                                                                             | Check the path or ID                                                                                                                           | No                       |
| 409  | `ACTIVE_RENTAL_EXISTS`   | The address already has a `pending` or `active` rental                                                                                                    | Poll the rental in `details.rental_id`                                                                                                         | No                       |
| 413  | `INVALID_REQUEST`        | Body larger than 16 KB                                                                                                                                    | Reduce the body size                                                                                                                           | No                       |
| 422  | `SIMULATION_FAILED`      | The transfer would fail on chain. `details.chain_message` holds the chain's message                                                                       | Check the sender's USDT balance                                                                                                                | After a fix              |
| 422  | `RECEIVER_NOT_ACTIVATED` | The [receiver](https://docs.luganodes.com/tron-energy/glossary.md) has never been activated on chain                                                      | Activate the address first, or set `activate_if_needed` to `true`                                                                              | After a fix              |
| 422  | `RECEIVER_IS_CONTRACT`   | The receiver is a smart contract                                                                                                                          | Send from a wallet address                                                                                                                     | No                       |
| 422  | `RENTAL_TOO_LARGE`       | Energy above `max_single_rental`                                                                                                                          | Request less energy                                                                                                                            | No                       |
| 429  | `RATE_LIMITED`           | Too many requests                                                                                                                                         | Retry after `Retry-After`                                                                                                                      | Yes, after `Retry-After` |
| 429  | `QUOTA_EXCEEDED`         | Daily energy quota or queued-rental cap used                                                                                                              | Contact us to raise the quota                                                                                                                  | After a fix              |
| 502  | `CHAIN_ERROR`            | The network was unreachable or the delegation did not land. A failed activation also returns it, with `details.activation_id` and `details.chain_message` | For a rental, check `GET /v1/rentals/{id}` and retry if the rental is `failed`. For an activation, read `details.chain_message` and call again | Yes, after checking      |
| 503  | `CAPACITY_EXHAUSTED`     | Estimated wait is longer than `max_wait_seconds`, or no energy is available. `details` has `reason` and `estimated_wait_seconds`                          | Send the transfer and pay TRX, or retry later                                                                                                  | Yes, later               |
| 503  | `SERVICE_UNAVAILABLE`    | Planned maintenance or an outage                                                                                                                          | Retry after `Retry-After`                                                                                                                      | Yes, after `Retry-After` |

Retry? values:

* **No**: the same request returns the same error. Change the request first.
* **After a fix**: send the request again once you have corrected the cause, such as the credentials, the clock, the balance or the activation.
* **Yes**: the same request can succeed. Follow the Action column.

## Common problems

| Symptom                                                                                | Where to look                                                                                                                                                          |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 UNAUTHORIZED` on requests that worked before, or on every request from one server | [Authentication and signing › Troubleshooting 401 errors](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md#troubleshooting-401-errors)      |
| A transaction signed before a queued rental became `active` expired                    | [Rental lifecycle › Queued requests](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md#queued-requests)                                     |
| `422 RECEIVER_NOT_ACTIVATED`, often an address that has only received USDT             | [Activate an address › Activating as part of a rental](https://docs.luganodes.com/tron-energy/energy-rental-api/activate-an-address.md#activating-as-part-of-a-rental) |

## Next steps

* [Conventions and limits](https://docs.luganodes.com/tron-energy/energy-rental-api/conventions-and-limits.md): rate limits, headers and which requests are safe to repeat.
