Errores

Formato de errores

Los errores llegan en una de tres formas. La mayoría de los endpoints usa la primera; las otras dos existen en rutas concretas y se listan aquí para que tu cliente no pase por alto un código de error que está buscando. Estándar. Un code para manejo programático, anidado en detail.error:

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

Límite de tasa a nivel de cuenta. Los mismos campos, pero en el nivel superior y sin detail: esta respuesta se produce antes de que la solicitud llegue al endpoint:

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

Plana. Los pasos de verificación de retiro colocan code junto a detail, y detail contiene el mensaje en sí:

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

No toda respuesta trae un código. Los fallos de validación de la solicitud llegan en el formato propio del framework, donde detail es un array de errores de campo y no una cadena; unas pocas comprobaciones internas devuelven {"detail": "..."} con un mensaje simple. Algunas respuestas 422 sí traen código, en la forma estándar — por ejemplo una clave de idempotencia reutilizada.

Lee el código del primero de estos campos que esté presente: detail.error.code, luego error.code, luego code. Si no hay ninguno, guíate por el estado HTTP, y nunca supongas que detail es una cadena: en la forma estándar es un objeto y, en un error de validación, un array.

Códigos de estado HTTP

Código	Significado
`200`	Éxito
`400`	Solicitud incorrecta — parámetros inválidos
`401`	No autorizado — clave API faltante o inválida
`402`	Pago requerido — saldo de la cuenta insuficiente
`403`	Prohibido — la clave carece del alcance requerido, IP fuera de la lista permitida o verificación requerida
`404`	No encontrado
`409`	Conflicto — solicitud duplicada o conflicto de recursos
`422`	Error de validación — verifica el cuerpo de la solicitud
`429`	Límite de tasa excedido — ver Límites de tasa
`500`	Error del servidor
`503`	Temporalmente no disponible — reintenta en breve

Códigos de error comunes

Se devuelven en la forma estándar, en detail.error.code:

Código	Estado	Descripción
`INVALID_TOKEN`	`401`	Clave API ausente, desconocida o deshabilitada
`ACCOUNT_BLOCKED`	`403`	Acceso a la API bloqueado para esta cuenta
`FORBIDDEN`	`403`	La clave carece del alcance que exige este endpoint, o la IP de la solicitud no está en la lista permitida de la clave
`NODE_API_KEY_ONLY`	`403`	Se envió una clave de Node API a esta API — solo funciona en `node.tronrental.com`
`INSUFFICIENT_BALANCE`	`402`	Saldo de la cuenta insuficiente para esta operación
`IDEMPOTENCY_KEY_REUSED`	`422`	Esta Idempotency-Key ya se usó con otro cuerpo de solicitud
`IDEMPOTENCY_KEY_TOO_LONG`	`422`	La Idempotency-Key tiene más de 64 caracteres
`INVALID_ADDRESS`	`400`	Dirección TRON no válida
`CONTRACT_ADDRESS_NOT_SUPPORTED`	`400`	El destino es un contrato inteligente — TRON prohíbe delegarle recursos
`INVALID_VOLUME`	`400`	La cantidad solicitada está fuera del rango permitido
`INVALID_DURATION`	`400`	La duración no es uno de los valores aceptados
`ORDER_NOT_FOUND`	`404`	El ID de orden no existe
`RATE_LIMIT_EXCEEDED`	`429`	Demasiadas solicitudes — ver Límites de tasa

Node API (node.tronrental.com) tiene sus propios códigos de error, en otro formato — consulta Node API → Límites y errores.

INSUFFICIENT_BALANCE no se usa en todas partes. POST /api/v1/smart-mode/activate y POST /api/v1/transfer-packages/buy informan la misma condición como 400, con mensaje y sin código: {"detail":{"error":{"message":"Insufficient balance"}}}. En esos dos endpoints, no detectes un problema de saldo solo por el código.

Códigos de Recarga automática

Se devuelven en la forma estándar desde los endpoints de Recarga automática:

Código	Estado	Descripción
`AUTOREFILL_ADDRESS_TAKEN`	`409`	La cuenta ya tiene una regla para esta dirección y este recurso — edita esa regla en su lugar
`AUTOREFILL_LIMIT_REACHED`	`409`	La cuenta ya tiene 20 reglas para este recurso; el límite también figura en `error.limit`
`AUTOREFILL_IN_PROGRESS`	`409`	Se está comprando una recarga para la regla en este momento — reintenta la edición o la eliminación en un minuto
`AUTOREFILL_DISABLED`	`503`	La Recarga automática de este recurso está desactivada temporalmente; solo se devuelve al crear una regla. No se creó ninguna regla — reintenta más tarde
`NOT_FOUND`	`404`	No existe esa regla en la cuenta

Códigos de verificación de retiro

POST /api/v1/account/withdrawal devuelve estos códigos de verificación en la forma plana, con code junto a detail. Los demás errores del mismo endpoint usan la forma estándar:

Código	Estado	Descripción
`WITHDRAW_SCOPE_REQUIRED`	`403`	La clave API carece del alcance `withdraw`
`2FA_REQUIRED`	`403`	Hay que activar 2FA, o proporcionar un código
`IP_WHITELIST_REQUIRED`	`403`	La clave necesita una lista de IP permitidas para retirar
`PASSKEY_REQUIRED`	`403`	La cuenta tiene una passkey — el retiro la exige
`INVALID_PASSKEY`	`403`	Desafío de passkey inválido, expirado o ajeno
`INVALID_2FA_CODE`	`403`	Código 2FA o de respaldo rechazado
`RATE_UNAVAILABLE`	`503`	Tipo de cambio temporalmente no disponible — reintenta en breve

Estrategia de reintentos

Reintenta las respuestas 5xx con retroceso exponencial. Para 429, prefiere la cabecera Retry-After cuando la respuesta la incluya, y lee primero el cuerpo: no todo 429 es un límite de tasa (ver Límites de tasa).

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")

Primeros pasos

Energía TRON

Formato de errores

Códigos de estado HTTP

Códigos de error comunes

Códigos de Recarga automática

Códigos de verificación de retiro

Estrategia de reintentos

​Formato de errores

​Códigos de estado HTTP

​Códigos de error comunes

​Códigos de Recarga automática

​Códigos de verificación de retiro

​Estrategia de reintentos

Formato de errores

Códigos de estado HTTP

Códigos de error comunes

Códigos de Recarga automática

Códigos de verificación de retiro

Estrategia de reintentos