Errors
Errors answer the usual envelope with a meaningful HTTP status:
JSON
{"code": 45009, "message": "insufficient balance", "data": null}Branch on code, not on message (the wording may change). Some errors carry details in data
(45014: {price_trx}; batch 45009: {needed, available}).
Request and order errors
| code | HTTP | meaning |
|---|---|---|
| 42200 | 422 | invalid request (the field is named in message) |
| 45001 | 400 | ordering is temporarily paused |
| 45003 | 400 | invalid TRON address |
| 45004 | 400 | energy below the allowed range |
| 45005 | 400 | energy above the allowed range |
| 45006 | 400 | term unavailable right now |
| 45009 | 400 | insufficient balance |
| 45010 | 409 | external_id reused with a different request |
| 45012 | 400 | that address belongs to the platform |
| 45014 | 409 | price above your max_price_trx (data.price_trx) |
| 45017 | 400 | USDT charging unavailable (no rate) |
| 45216 | 400 | test mode not supported on this endpoint |
| 40420 | 404 | order not found |
| 46008 | 404 | saved address not found |
| 46010 | 400 | Idempotency-Key missing |
| 46011 | 409 | the request with that Idempotency-Key is still in progress |
Authentication errors
| code | HTTP | meaning |
|---|---|---|
| 45201 | 401 | credentials missing |
| 45202 | 401 | unknown access id or wrong secret |
| 45203 | 401 | signature mismatch (or malformed nonce) |
| 45204 | 401 | X-Timestamp outside ±300 s |
| 45205 | 401 | X-Nonce already used |
| 45210 | 401 | this key uses the other authentication mode |
| 45206 | 403 | your IP is not on the key's allow-list |
| 45207 | 403 | the key lacks the permission (Read / Order) |
| 45208 | 403 | key disabled, suspended or expired |
| 46003 | 403 | account frozen — contact support |
| 45209 | 429 | rate limit — slow down |
POST /v1/auth/echo explains every authentication failure — see
Authentication.
Server errors
| code | HTTP | meaning |
|---|---|---|
| 50010 | 500 | delegation temporarily unavailable — retry later with the same external_id |
| 50000 | 500 | unexpected error — retry later with the same external_id |
Key management (website)
These come from Account → API keys, not from /v1:
| code | meaning |
|---|---|
| 45211 | key limit reached (20 live keys) |
| 45212 | callback_url must be a public https:// URL |
| 45213 | API key not found |
| 45218 | allowed_ips entries must be IP addresses or CIDR ranges |
| 46004 | enable two-factor authentication first |
| 40104 / 40105 / 40106 | authenticator code missing / wrong / already used |
Retrying safely
4xx(except429): fix the request — retrying it unchanged gives the same answer.429: wait for the next minute; watchX-RateLimit-Remaining.5xxor a timeout: retryPOST /v1/orderswith the sameexternal_id— you are never charged twice.