Erros

Formato de erros

Os erros chegam em um de três formatos. A maioria dos endpoints usa o primeiro; os outros dois existem em caminhos específicos e estão listados aqui para que o seu cliente não deixe de encontrar um código de erro que procura. Padrão. Um code para tratamento programático, aninhado em detail.error:

{
  "detail": {
    "error": {
      "code": "INSUFFICIENT_BALANCE",
      "message": "Insufficient balance. Required: 12.5 TRX, available: 3.1 TRX"
    }
  }
}

Limite de taxa no nível da conta. Os mesmos campos, porém no nível superior, sem detail — esta resposta é produzida antes de a requisição chegar ao endpoint:

{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}

Plano. As etapas de verificação de saque colocam code ao lado de detail, e detail contém a própria mensagem:

{"detail":"Passkey verification required","code":"PASSKEY_REQUIRED"}

Nem toda resposta traz um código. Falhas de validação da requisição voltam no formato próprio do framework, em que detail é um array de erros de campo, não uma string, e algumas verificações internas retornam {"detail": "..."} com uma mensagem simples. Algumas respostas 422 trazem sim um código, no formato padrão — uma chave de idempotência reutilizada, por exemplo.

Leia o código do primeiro campo presente: detail.error.code, depois error.code, depois code. Recorra ao status HTTP quando nenhum deles existir, e nunca presuma que detail é uma string: no formato padrão ele é um objeto e, num erro de validação, um array.

Códigos de status HTTP

Código	Significado
`200`	Sucesso
`400`	Requisição inválida — parâmetros incorretos
`401`	Não autorizado — chave de API ausente ou inválida
`402`	Pagamento necessário — saldo da conta insuficiente
`403`	Proibido — a chave não tem o escopo exigido, IP fora da lista permitida ou verificação necessária
`404`	Não encontrado
`409`	Conflito — requisição duplicada ou conflito de recurso
`422`	Erro de validação — verifique o corpo da requisição
`429`	Limite de taxa excedido — veja Limites de Taxa
`500`	Erro do servidor
`503`	Temporariamente indisponível — tente novamente em breve

Códigos de erro comuns

Retornados no formato padrão, em detail.error.code:

Código	Status	Descrição
`INVALID_TOKEN`	`401`	Chave de API ausente, desconhecida ou desativada
`ACCOUNT_BLOCKED`	`403`	Acesso à API bloqueado para esta conta
`FORBIDDEN`	`403`	A chave não tem o escopo exigido por este endpoint, ou o IP da requisição não está na lista permitida da chave
`NODE_API_KEY_ONLY`	`403`	Uma chave do Node API foi enviada a esta API — ela funciona apenas em `node.tronrental.com`
`INSUFFICIENT_BALANCE`	`402`	Saldo da conta insuficiente para esta operação
`IDEMPOTENCY_KEY_REUSED`	`422`	Esta Idempotency-Key já foi usada com outro corpo de requisição
`IDEMPOTENCY_KEY_TOO_LONG`	`422`	A Idempotency-Key tem mais de 64 caracteres
`INVALID_ADDRESS`	`400`	Endereço TRON inválido
`CONTRACT_ADDRESS_NOT_SUPPORTED`	`400`	O destino é um contrato inteligente — a TRON proíbe delegar recursos a ele
`INVALID_VOLUME`	`400`	Quantidade solicitada fora do intervalo permitido
`INVALID_DURATION`	`400`	Duração não está entre os valores aceitos
`ORDER_NOT_FOUND`	`404`	O ID do pedido não existe
`RATE_LIMIT_EXCEEDED`	`429`	Requisições em excesso — veja Limites de Taxa

O Node API (node.tronrental.com) tem códigos de erro próprios, em outro formato — veja Node API → Limites e erros.

INSUFFICIENT_BALANCE não é usado em todos os lugares. POST /api/v1/smart-mode/activate e POST /api/v1/transfer-packages/buy relatam a mesma condição como 400, com mensagem e sem código: {"detail":{"error":{"message":"Insufficient balance"}}}. Nesses dois endpoints, não detecte um problema de saldo apenas pelo código.

Códigos da Recarga automática

Retornados no formato padrão pelos endpoints de Recarga automática:

Código	Status	Descrição
`AUTOREFILL_ADDRESS_TAKEN`	`409`	A conta já tem uma regra para este endereço e recurso — edite essa regra
`AUTOREFILL_LIMIT_REACHED`	`409`	A conta já tem 20 regras para este recurso; o limite também vem em `error.limit`
`AUTOREFILL_IN_PROGRESS`	`409`	Uma recarga da regra está sendo comprada neste momento — repita a edição ou a exclusão em um minuto
`AUTOREFILL_DISABLED`	`503`	A Recarga automática deste recurso está temporariamente desativada; retornado apenas ao criar uma regra. Nenhuma regra foi criada — tente novamente mais tarde
`NOT_FOUND`	`404`	Não existe essa regra na conta

Códigos de verificação de saque

POST /api/v1/account/withdrawal retorna estes códigos de verificação no formato plano, com code ao lado de detail. Os demais erros do mesmo endpoint usam o formato padrão:

Código	Status	Descrição
`WITHDRAW_SCOPE_REQUIRED`	`403`	A chave de API não tem o escopo `withdraw`
`2FA_REQUIRED`	`403`	É preciso ativar o 2FA, ou fornecer um código
`IP_WHITELIST_REQUIRED`	`403`	A chave precisa de uma lista de IPs permitidos para sacar
`PASSKEY_REQUIRED`	`403`	A conta tem uma passkey — o saque a exige
`INVALID_PASSKEY`	`403`	Desafio de passkey inválido, expirado ou de outra conta
`INVALID_2FA_CODE`	`403`	Código 2FA ou de backup recusado
`RATE_UNAVAILABLE`	`503`	Taxa de câmbio temporariamente indisponível — tente novamente em breve

Estratégia de novas tentativas

Repita respostas 5xx com recuo exponencial. Para 429, prefira o cabeçalho Retry-After quando a resposta o trouxer, e leia o corpo primeiro — nem todo 429 é um limite de taxa (veja Limites de Taxa).

import time
import requests

def api_call_with_retry(url, **kwargs):
    for attempt in range(3):
        resp = requests.get(url, **kwargs)
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
            continue
        if resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        return resp
    raise Exception("Max retries exceeded")

Primeiros passos

Energia TRON

Formato de erros

Códigos de status HTTP

Códigos de erro comuns

Códigos da Recarga automática

Códigos de verificação de saque

Estratégia de novas tentativas

​Formato de erros

​Códigos de status HTTP

​Códigos de erro comuns

​Códigos da Recarga automática

​Códigos de verificação de saque

​Estratégia de novas tentativas

Formato de erros

Códigos de status HTTP

Códigos de erro comuns

Códigos da Recarga automática

Códigos de verificação de saque

Estratégia de novas tentativas