Códigos de Error - Documentación de API

Formato de Respuesta de Error

Todas las respuestas de error usan un formato unificado:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Mensaje de error legible para humanos",
    "details": "Contexto adicional (opcional)"
  }
}

💡 Use error.code como una condición de ramificación estable (el mensaje puede cambiar)

Códigos de Estado HTTP

200 OK

Solicitud exitosa

200

201 Creado

Recurso creado exitosamente

201

400 Solicitud Incorrecta

Los parámetros de la solicitud son inválidos

400

{
  "code": "INVALID_REQUEST",
  "message": "Formato de solicitud inválido"
}

401 No Autorizado

No autorizado o clave API inválida

401

{
  "code": "UNAUTHORIZED",
  "message": "Clave API inválida o expirada"
}

403 Prohibido

Saldo de cuenta insuficiente o permisos insuficientes

403

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "El saldo de la cuenta es insuficiente"
}

404 No Encontrado

Recurso no encontrado

404

{
  "code": "ORDER_NOT_FOUND",
  "message": "Pedido no encontrado"
}

409 Conflicto

Conflicto de recursos

409

{
  "code": "ADDRESS_EXISTS",
  "message": "La dirección ya existe"
}

429 Demasiadas Solicitudes

Límite de tasa de solicitudes de clave API excedido

429

{
  "code": "RATE_LIMITED",
  "message": "Límite de tasa excedido"
}

500 Error Interno del Servidor

Error interno del servidor

500

{
  "code": "INTERNAL_ERROR",
  "message": "Ocurrió un error inesperado"
}

503 Servicio No Disponible

Servicio temporalmente no disponible (en mantenimiento)

503

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "El servicio está temporalmente no disponible"
}

Códigos de Error Comunes

Error Code	Status	Description	Solution
UNAUTHORIZED	401	La clave API es inválida, expiró o fue revocada	Verifique si la clave API es correcta, cree una nueva si es necesario
INSUFFICIENT_BALANCE	403	Saldo de cuenta insuficiente	Recargue el saldo de la cuenta
INVALID_ADDRESS	400	Formato de dirección TRON inválido	Verifique si la dirección es una dirección TRON válida (comienza con T)
INVALID_ENERGY_AMOUNT	400	Cantidad de energía inválida	La cantidad de energía debe ser un número entero positivo, recomendado 65000 para transferencias USDT
INVALID_DURATION	400	Duración de alquiler inválida	Use duraciones válidas: 1H, 1D, 3D, 7D, 14D, 30D
ORDER_NOT_FOUND	404	El pedido no existe	Verifique si el ID del pedido es correcto
ADDRESS_EXISTS	409	La dirección ya existe	Verifique si la dirección ya ha sido agregada, o use la dirección existente
RATE_LIMITED	429	Límite de tasa de solicitudes de clave API excedido (actualmente solo se aplica a POST /v1/wallet/recharges)	Implemente reintento con retroceso exponencial, o reduzca la frecuencia de llamadas

Cómo Manejar

Error	Handling
401 UNAUTHORIZED	Verificar/rotar clave API
403 INSUFFICIENT_BALANCE	Recargar o reducir cantidad de solicitud
409 ADDRESS_EXISTS	Cambiar a consulta/manejo idempotente
429 RATE_LIMITED	Reintento con retroceso (seguir Retry-After si está presente, de lo contrario retroceso exponencial)
5xx	Reintentar + registrar contexto de solicitud

Directrices de Reintento

• reintentos máximos: 3
• retroceso: exponencial (1s, 2s, 4s...)
• solo reintentar 429/5xx
• no reintentar 4xx (errores del cliente)

Códigos de Error y Manejo