Обработка ошибок
Формат ответов об ошибках, коды ошибок и рекомендации по обработке.
Формат ответа об ошибке
Все ошибки API возвращаются в едином формате:
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Insufficient wallet balance. Please top up your wallet."
}
}| Поле | Тип | Описание |
|---|---|---|
request_id | string (UUIDv4) | Уникальный идентификатор запроса для трассировки. Присутствует в ответах Management API. Используйте при обращении в поддержку. |
error.code | string | Машиночитаемый код ошибки |
error.message | string | Человекочитаемое описание; безопасно для отображения пользователю |
error.details | object | Опционально, может отсутствовать. Дополнительный контекст (зависит от кода ошибки) |
Таблица кодов ошибок
| HTTP | Код | Когда возникает | Повтор? |
|---|---|---|---|
| 401 | UNAUTHORIZED | Невалидный, отозванный или истёкший API-ключ | Нет — исправьте или ротируйте ключ |
| 402 | PAYMENT_REQUIRED | Недостаточный баланс кошелька | Нет — пополните баланс |
| 402 | SPEND_LIMIT_EXCEEDED | Достигнут ежемесячный лимит расходов организации | Нет — увеличьте лимит или дождитесь нового месяца |
| 403 | FORBIDDEN | Нет прав (например, инженер пытается создать ключ организации) | Нет |
| 409 | IDEMPOTENCY_CONFLICT | Дублирование idempotency key с запросом в обработке | Да — после задержки |
| 422 | API_KEY_LIMIT_REACHED | Слишком много активных API-ключей (10 личных / 50 организации) | Нет — отзовите неиспользуемые ключи |
| 429 | RATE_LIMITED | Превышен лимит запросов (requests per minute) | Да — используйте заголовок Retry-After |
| 500 | INTERNAL_ERROR | Непредвиденная ошибка сервера | Да — с exponential backoff |
| 503 | SERVICE_UNAVAILABLE | Сервис временно недоступен | Да — с exponential backoff |
Различие кодов 402
Оба кода PAYMENT_REQUIRED и SPEND_LIMIT_EXCEEDED возвращают HTTP 402, но означают разные ситуации. Всегда проверяйте поле error.code, а не только HTTP-статус.
| Код | Причина | Действие |
|---|---|---|
PAYMENT_REQUIRED | Баланс кошелька равен нулю или ниже стоимости запроса | Пополните баланс через дашборд или API оплаты |
SPEND_LIMIT_EXCEEDED | Организация достигла ежемесячного лимита расходов | Owner/admin увеличивает лимит или дождитесь нового месяца |
Дополнительные данные (details)
Некоторые ошибки содержат дополнительный контекст в поле error.details:
Поле details может отсутствовать в некоторых ответах.
| Код | Содержимое details |
|---|---|
PAYMENT_REQUIRED | { "balance_kopecks": 0, "required_kopecks": 42 } |
SPEND_LIMIT_EXCEEDED | { "limit_kopecks": 100000, "spent_kopecks": 100000, "resets_at": "2026-05-01T00:00:00Z" } |
RATE_LIMITED | { "retry_after_seconds": 12 } |
API_KEY_LIMIT_REACHED | { "current_count": 10, "max_count": 10 } |
IDEMPOTENCY_CONFLICT | { "existing_request_id": "..." } |
| Все остальные | {} |
Рекомендации по повторным запросам
Повторяйте запросы только для ошибок, отмеченных как retriable:
429 RATE_LIMITED— дождитесь значения из заголовкаRetry-After409 IDEMPOTENCY_CONFLICT— подождите несколько секунд, затем повторите500 INTERNAL_ERRORи503 SERVICE_UNAVAILABLE— используйте exponential backoff (начиная с 1 секунды, максимум 5 попыток)
Не повторяйте запросы для 401, 402, 403, 422 — эти ошибки требуют действий от пользователя.
Использование request_id
Все ответы API содержат поле request_id (UUIDv4). При обращении в поддержку указывайте этот идентификатор — он позволяет быстро найти и диагностировать проблему.