FAQ
Часто задаваемые вопросы по Konergy API: ошибки аутентификации, биллинг, лимиты и отладка.
Почему я получаю 401 Unauthorized?
Ошибка 401 UNAUTHORIZED означает, что API-ключ невалиден, отозван или истёк. Убедитесь, что:
- ключ передаётся в заголовке
Authorization: Bearer sk_konergy_... - ключ не был отозван через дашборд или Management API
- при ротации ключей сервис использует актуальный ключ (см. Ротация ключей)
Почему 400 IDEMPOTENCY_KEY_REQUIRED?
Все POST-мутации требуют заголовок idempotency-key в формате UUIDv4. Если заголовок отсутствует или имеет невалидный формат, API возвращает 400 IDEMPOTENCY_KEY_REQUIRED.
curl -X POST https://api.konergy.ru/api/jobs/process \
-H "Authorization: Bearer sk_konergy_..." \
-H "idempotency-key: 550e8400-e29b-41d4-a716-446655440000"Подробнее см. Аутентификация.
Почему 402 PAYMENT_REQUIRED?
Баланс предоплатного кошелька (prepaid wallet) равен нулю или ниже стоимости запроса. Пополните баланс через дашборд биллинга или API оплаты.
Подробнее о двух кодах 402 см. в разделе Обработка ошибок.
Почему 402 SPEND_LIMIT_EXCEEDED?
Организация достигла ежемесячного лимита расходов (spend limit). Это отличается от PAYMENT_REQUIRED: средства на кошельке есть, но установленный лимит исчерпан.
- Owner или admin организации может увеличить лимит через Management API или дашборд
- Поле
error.details.resets_atпоказывает дату сброса лимита
Почему 429 RATE_LIMITED?
Превышен лимит запросов в минуту (RPM). Используйте заголовок Retry-After из ответа, чтобы определить, когда можно повторить запрос. Рекомендуется exponential backoff.
Подробнее см. Лимиты запросов.
Как проверить баланс?
Два способа:
- API:
GET /billing/me/summaryвозвращает текущий баланс кошелька, лимиты и использование за период - Дашборд: konergy.ru/app/account/billing
Как увеличить лимиты?
Лимиты запросов (rate limits) настраиваются для каждого API-ключа. Для увеличения лимитов:
- измените лимиты расходов через Management API или дашборд
- при необходимости индивидуальных условий обратитесь в поддержку
Можно ли получить результат без polling?
Да. Добавьте заголовок Prefer: wait=30 к запросу — сервер подождёт до 30 секунд и вернёт результат сразу (200 OK). Подробнее в руководстве по синхронному режиму.
Какое максимальное время ожидания?
45 секунд (Prefer: wait=45). Если обработка не завершится за это время, сервер вернёт 202 Accepted с jobId, и вы сможете продолжить через polling.