Common Errors (TronScan)

The error contract is the HTTP status code. TronScan error response bodies are not yet standardized; therefore this document only specifies HTTP status codes and does not define a unified error body structure.

1. HTTP Status Codes

Status	Meaning	Retryable	Notes
`200 OK`	Success	—	Parse the response body
`400 Bad Request`	Invalid request	No	Parameter format error or missing required parameter; some endpoints return a `{"message":"..."}` error body
`401 Unauthorized`	Missing or invalid Key	No	Returned when an endpoint that requires a Key is called without one (see the individual endpoint’s “Endpoint & Authentication” section)
`403 Forbidden`	Access denied / insufficient permissions	No	API Key lacks permissions or has been blocked
`404 Not Found`	Path or resource not found	No	—
`410 Gone`	Resource gone / Deprecated	No	The endpoint has been permanently decommissioned and is no longer available; callers must migrate to alternative endpoints
`429 Too Many Requests`	Rate limit triggered	Yes	Retry after back-off; wait the seconds specified in the `Retry-After` response header (rate limiting is global; see the API Keys documentation)
`5xx`	Server error	Yes	Retry after back-off

2. Important Behavior (agents must know)

Some parameter violations are silently handled: for example, when limit exceeds its maximum or start+limit is too large, the API does not return an error — it silently truncates/ignores and returns 200 with data. Agents cannot rely on errors to detect parameter violations; they must validate parameters against the documented constraints themselves.
Error response bodies are not standardized: different endpoints may return different body shapes on error — possibly empty, {"message":"..."} (e.g., account/wallet returns 400 + {"message":"some parameters are invalid or out of range"} on missing params), or other structures. A unified error body is not currently specified; use HTTP status codes as the authoritative signal.

3. Empty Result ≠ Error

Scenario	Correct Response	Agent Behavior
List with no matches	`200` + data array `[]`; `total` is still returned	Normal empty list; treat as not-found, not an error

4. Reference Usage

Individual endpoint “Errors” sections do not repeat this table. They only note: ① any error scenarios specific to that endpoint (if any); and ② “For generic HTTP status codes, see Common Errors.”