FAQ

Почему я получаю 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://platform-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.