Error Codes

This page provides information about the error codes that can be returned by the TronZap API.

Error Response Format

When an error occurs, the API will return a response with a non-zero error code and an error message:

{
    "code": 1,
    "key": "auth",
    "request_id": "99d8b507-0bca-4d5a-9542-cc2a2f2e3639",
    "error": "Incorrect token or signature"
}

Error Code List

Code	Key	Description	Resolution
0	—	Success	Not an error. The request was successful.
1	auth	Authentication error	Check your API token and ensure your signature is calculated correctly.
2	invalid_service_or_params	Invalid service or parameters	Check that the service name and parameters are correct.
5	wallet_not_found	Wallet not found	Verify the wallet address or contact support if you believe this is an error.
6	insufficient_funds	Insufficient funds	Add funds to your account or reduce the amount of energy you're requesting.
10	invalid_tron_address	Invalid TRON address	Check the TRON address format. It should be a valid 34-character TRON address.
11	invalid_energy_amount	Invalid energy amount	Ensure the requested energy amount is valid.
12	invalid_duration	Invalid duration	Check that the duration parameter is valid.
50	invalid_bandwidth_amount	Invalid bandwidth amount	Ensure the requested bandwidth amount is valid.
20	subscription_not_found	Subscription not found	Verify the subscription ID or external ID is correct.
21	cannot_stop_subscription	Cannot stop subscription	Review subscription limits; adjust the transaction limit or complete pending transactions.
24	address_not_activated	Address not activated	Activate the address first by making an address activation transaction.
25	address_already_activated	Address already activated	The address is already activated. No action needed.
30	aml_check_not_found	AML check not found	Re-run the AML check or contact support to confirm the verification status.
35	service_unavailable	Service not available	The service is temporarily unavailable for use.
500	internal_server_error	Internal server error	Contact support if this error persists.

Sub-keys

Some errors may include a more specific sub-key that provides additional context. Sub-keys use dot notation (e.g., invalid_tron_address.from_address).

Base Key	Sub-key	Description
invalid_tron_address	invalid_tron_address.from_address	Invalid from address
invalid_tron_address	invalid_tron_address.to_address	Invalid to address
invalid_tron_address	invalid_tron_address.contract_address	Invalid contract address
invalid_tron_address	invalid_tron_address.already_subscribed	Address already has an active subscription
invalid_service_or_params	invalid_service_or_params.network	Unsupported network
invalid_service_or_params	invalid_service_or_params.address	Invalid address provided
invalid_service_or_params	invalid_service_or_params.hash	Hash is required for hash checks
invalid_service_or_params	invalid_service_or_params.direction	Direction is missing or invalid (required for hash checks)
invalid_service_or_params	invalid_service_or_params.page	Invalid page
invalid_service_or_params	invalid_service_or_params.per_page	Invalid per_page
invalid_service_or_params	invalid_service_or_params.status	Invalid status
invalid_service_or_params	invalid_service_or_params.id	Invalid id / Either id or external_id is required
invalid_service_or_params	invalid_service_or_params.external_id	Invalid external_id
invalid_service_or_params	invalid_service_or_params.address_owner	Address belongs to another user
invalid_service_or_params	invalid_service_or_params.internal_credit	Internal credit not allowed
invalid_service_or_params	invalid_service_or_params.amount	Amount out of range
invalid_service_or_params	invalid_service_or_params.exchange_finalized	Exchange finalized
invalid_service_or_params	invalid_service_or_params.exchange_state	Exchange in invalid state
invalid_energy_amount	invalid_energy_amount.energy_amount	Invalid energy amount
invalid_energy_amount	invalid_energy_amount.bandwidth_amount	Invalid bandwidth amount
invalid_duration	invalid_duration.duration	Duration must be equal to 1 (1 hour)
address_not_activated	address_not_activated.subscription	Address must be activated before purchasing subscription
subscription_not_found	subscription_not_found.transaction	Transaction not found

Handling Errors

When consuming the API, you should implement error handling logic for all possible error codes. Here are some recommendations:

Authentication Errors (Code 1)

Authentication errors indicate issues with your API credentials or signature calculation. You should:

• Verify your API token is correct
• Check your signature calculation logic
• Ensure your API secret is not exposed in client-side code

Resource Errors (Codes 5, 6, 10, 20)

Resource errors indicate issues with the provided resources. You should:

• Validate TRON addresses before sending them to the API
• Check account balance before making transactions
• Verify transaction IDs when checking status

Business Logic Errors (Codes 24, 25)

Business logic errors indicate issues with the requested operation. You should:

• Implement address activation check before attempting energy purchase
• Skip address activation if already activated