Коды ошибок и обработка
Понимание и обработка ошибок API
Формат ответа с ошибкой
Все ответы с ошибками используют единый формат:
{
"error": {
"code": "ERROR_CODE",
"message": "Человекочитаемое сообщение об ошибке",
"details": "Дополнительный контекст (опционально)"
}
}💡 Используйте error.code в качестве стабильного условия ветвления (message может изменяться)
Коды статуса HTTP
200 OK
Запрос выполнен успешно
201 Created
Ресурс успешно создан
400 Bad Request
Параметры запроса недействительны
{
"code": "INVALID_REQUEST",
"message": "Неверный формат запроса"
}401 Unauthorized
Не авторизован или недействительный API-ключ
{
"code": "UNAUTHORIZED",
"message": "Недействительный или истекший API-ключ"
}403 Forbidden
Недостаточный баланс аккаунта или прав доступа
{
"code": "INSUFFICIENT_BALANCE",
"message": "Баланс аккаунта недостаточен"
}404 Not Found
Ресурс не найден
{
"code": "ORDER_NOT_FOUND",
"message": "Заказ не найден"
}409 Conflict
Конфликт ресурсов
{
"code": "ADDRESS_EXISTS",
"message": "Адрес уже существует"
}429 Too Many Requests
Превышен лимит частоты запросов для API-ключа
{
"code": "RATE_LIMITED",
"message": "Превышен лимит частоты запросов"
}500 Internal Server Error
Внутренняя ошибка сервера
{
"code": "INTERNAL_ERROR",
"message": "Произошла непредвиденная ошибка"
}503 Service Unavailable
Сервис временно недоступен (на обслуживании)
{
"code": "SERVICE_UNAVAILABLE",
"message": "Сервис временно недоступен"
}Распространенные коды ошибок
| Error Code | Status | Description | Solution |
|---|---|---|---|
| UNAUTHORIZED | 401 | API-ключ недействителен, истек или отозван | Проверьте правильность API-ключа, при необходимости создайте новый |
| INSUFFICIENT_BALANCE | 403 | Недостаточный баланс аккаунта | Пополните баланс аккаунта |
| INVALID_ADDRESS | 400 | Неверный формат TRON-адреса | Проверьте, является ли адрес действительным TRON-адресом (начинается с T) |
| INVALID_ENERGY_AMOUNT | 400 | Неверное количество энергии | Количество энергии должно быть положительным целым числом, рекомендуется 65000 для переводов USDT |
| INVALID_DURATION | 400 | Неверная длительность аренды | Используйте допустимые длительности: 1H, 1D, 3D, 7D, 14D, 30D |
| ORDER_NOT_FOUND | 404 | Заказ не существует | Проверьте правильность ID заказа |
| ADDRESS_EXISTS | 409 | Адрес уже существует | Проверьте, не был ли адрес уже добавлен, или используйте существующий адрес |
| RATE_LIMITED | 429 | Превышен лимит частоты запросов для API-ключа (в настоящее время применяется только к POST /v1/wallet/recharges) | Реализуйте повтор с экспоненциальной задержкой или уменьшите частоту вызовов |
Как обрабатывать
| Error | Handling |
|---|---|
| 401 UNAUTHORIZED | Проверить/сменить API-ключ |
| 403 INSUFFICIENT_BALANCE | Пополнить баланс или уменьшить сумму запроса |
| 409 ADDRESS_EXISTS | Переключиться на запрос/идемпотентную обработку |
| 429 RATE_LIMITED | Повтор с задержкой (следуйте Retry-After если есть, иначе экспоненциальная задержка) |
| 5xx | Повтор + логирование контекста запроса |
Рекомендации по повторам
- • максимум повторов: 3
- • задержка: экспоненциальная (1с, 2с, 4с...)
- • повторять только 429/5xx
- • не повторять 4xx (ошибки клиента)