Códigos de Erro & Tratamento
Entender e tratar erros da API
Formato de Resposta de Erro
Todas as respostas de erro usam o formato padrão:
{
"error": {
"code": "ERROR_CODE",
"message": "Mensagem de erro legível",
"details": "Contexto adicional (opcional)"
}
}💡 Use error.code como condição de ramificação estável (message pode mudar)
Códigos de Status HTTP
200 OK
Requisição bem-sucedida
201 Created
Criação de recurso bem-sucedida
400 Bad Request
Parâmetros da requisição inválidos
{
"code": "INVALID_REQUEST",
"message": "Formato da requisição inválido"
}401 Unauthorized
Não autenticado ou API Key inválida
{
"code": "UNAUTHORIZED",
"message": "API key inválida ou expirada"
}403 Forbidden
Saldo da conta insuficiente ou sem permissão
{
"code": "INSUFFICIENT_BALANCE",
"message": "Saldo da conta insuficiente"
}404 Not Found
Recurso não encontrado
{
"code": "ORDER_NOT_FOUND",
"message": "Pedido não encontrado"
}409 Conflict
Conflito de recurso
{
"code": "ADDRESS_EXISTS",
"message": "Endereço já existe"
}429 Too Many Requests
Excedeu o limite de taxa da API Key
{
"code": "RATE_LIMITED",
"message": "Excedeu o limite de taxa"
}500 Internal Server Error
Erro interno do servidor
{
"code": "INTERNAL_ERROR",
"message": "Ocorreu um erro inesperado"
}503 Service Unavailable
Serviço temporariamente indisponível (em manutenção)
{
"code": "SERVICE_UNAVAILABLE",
"message": "Serviço temporariamente indisponível"
}Códigos de Erro Comuns
| Error Code | Status | Description | Solution |
|---|---|---|---|
| UNAUTHORIZED | 401 | API Key inválida, expirada ou revogada | Verifique se a API Key está correta, crie uma nova se necessário |
| INSUFFICIENT_BALANCE | 403 | Saldo da conta insuficiente | Recarregue a conta |
| INVALID_ADDRESS | 400 | Formato de endereço TRON inválido | Verifique se o endereço é um endereço TRON válido (começa com T) |
| INVALID_ENERGY_AMOUNT | 400 | Quantidade de energia inválida | A quantidade de energia deve ser um número inteiro positivo, recomendado 65000 para transferência USDT |
| INVALID_DURATION | 400 | Duração do aluguel inválida | Use durações válidas: 1H, 1D, 3D, 7D, 14D, 30D |
| ORDER_NOT_FOUND | 404 | Pedido não existe | Verifique se o ID do pedido está correto |
| ADDRESS_EXISTS | 409 | Endereço já existe | Verifique se o endereço já foi adicionado ou use o endereço existente |
| RATE_LIMITED | 429 | Excedeu o limite de taxa da API Key (atualmente aplicável apenas para POST /v1/wallet/recharges) | Implemente retry com exponential backoff ou reduza a frequência de chamadas |
Como Tratar
| Error | Handling |
|---|---|
| 401 UNAUTHORIZED | Verifique/rotacione a API Key |
| 403 INSUFFICIENT_BALANCE | Recarregue ou reduza a quantidade solicitada |
| 409 ADDRESS_EXISTS | Mude para consulta/tratamento idempotente |
| 429 RATE_LIMITED | Retry com backoff (siga Retry-After se disponível, caso contrário use exponential backoff) |
| 5xx | Retry + registre contexto da requisição |
Diretrizes de Retry
- • máximo de retries: 3 vezes
- • backoff: exponencial (1s, 2s, 4s...)
- • apenas retry 429/5xx
- • não faça retry 4xx (erro do lado do cliente)