> 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/conventions-and-limits.md).

# Conventions and limits

Base URL, formats, IDs, versioning, rate limits and retries.

These rules apply to every Energy Rental API request and response.

## Base URL

Every endpoint is relative to the base URL we share with your credentials. The samples in these docs call it `$BASE_URL`, and every path starts with `/v1`.

```bash
export BASE_URL="https://<your-base-url>"
```

## Conventions

| Topic         | Rule                                                                                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Format        | JSON over HTTPS, UTF-8. Send `Content-Type: application/json` on requests with a body                                                                           |
| Addresses     | Base58 (`T...`)                                                                                                                                                 |
| Token amounts | Strings in the smallest unit. 1 USDT = `"1000000"`                                                                                                              |
| Energy        | Integers                                                                                                                                                        |
| Times         | ISO 8601, UTC                                                                                                                                                   |
| IDs           | Prefixed: `rnt_` for rentals, `act_` for activations, `req_` for requests. Every response carries `X-Request-Id`, also returned as `request_id` in error bodies |
| Versioning    | `/v1` in the path. New fields, error codes and status reasons are added without a version change                                                                |
| Body size     | Up to 16 KB. A larger body returns `413`                                                                                                                        |

Because new fields, error codes and status reasons can appear without a version change, ignore fields you do not recognise and handle an unknown error code by its HTTP status.

## Rate limits

Limits are set per API key and agreed during onboarding. A request over the limit returns `429 RATE_LIMITED` with a `Retry-After` header. Wait for the time in `Retry-After`, then send the request again.

A daily energy quota and a cap on queued rentals apply separately. A request that exceeds either returns `429 QUOTA_EXCEEDED`. Contact us to raise the quota.

## Response headers

The request headers `X-API-Key`, `X-Timestamp` and `X-Signature` are described in [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md). Responses carry these headers:

| Header                | Sent on                                       | Meaning                                                                         |
| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
| `X-Request-Id`        | Every response                                | The ID of the request. Quote it when you contact us                             |
| `RateLimit-Limit`     | Every response                                | The request limit set for your API key                                          |
| `RateLimit-Remaining` | Every response                                | How much of that limit is left. Reduce your request rate before it reaches zero |
| `Retry-After`         | `429` responses and `503 SERVICE_UNAVAILABLE` | How long to wait before you send the request again                              |

## Retries and idempotency

A timeout or a dropped connection leaves a request with an unknown outcome. This table shows which requests are safe to send again.

| Request                      | Safe to repeat?                                      | What happens when you repeat it                                                                                                              |
| ---------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Any `GET`                    | Yes                                                  | The request only reads data                                                                                                                  |
| `POST /v1/estimate`          | Yes                                                  | The transfer is simulated again and no rental is created                                                                                     |
| `POST /v1/accounts/activate` | Yes                                                  | An address that is already active returns `200` with `already_active: true`. No activation takes place                                       |
| `POST /v1/rentals`           | Yes, while the first rental is `pending` or `active` | The API returns `409 ACTIVE_RENTAL_EXISTS` with the existing `rental_id`. After the first rental ends, the same request creates a new rental |

If a `POST /v1/rentals` call times out, run the check in [Create a rental › Retry behaviour](https://docs.luganodes.com/tron-energy/energy-rental-api/create-a-rental.md#retry-behaviour) before you send it again.

For retry guidance by error code, see the Retry? column in [Errors](https://docs.luganodes.com/tron-energy/energy-rental-api/errors.md).

## Next steps

* [API reference](https://docs.luganodes.com/tron-energy/energy-rental-api.md): every Energy Rental API endpoint, with its method, path and what it does.
