Данные API-ключа недействительны: причины этой ошибки и способы её устранения

Если при вызове hiapi вы видите сообщение вроде "the api keys data are invalid" (или аналогичный вариант, который выдаёт ваше приложение), это означает, что запрос вообще не прошёл аутентификацию. На нижнем уровне собственный API hiapi возвращает для этого конкретную ошибку: HTTP 401, error.code: "permission_denied" с сообщением "This API key is invalid. Check that it is correct or use another API key and try again." (Этот API-ключ недействителен. Проверьте, что он указан верно, или используйте другой API-ключ и попробуйте снова.) Любое приложение, оборачивающее hiapi — серверный прокси, клиент, совместимый с OpenAI, внутренний SDK — переупаковывает тот же самый 401 в собственные формулировки; именно поэтому точный текст, который вы видите, редко совпадает с оригиналом от hiapi. Это руководство шаг за шагом объясняет, почему это происходит и как за несколько минут подтвердить и устранить проблему.

Как на самом деле выглядит ошибка

Неудачный запрос к POST https://api.hiapi.ai/v1/tasks (или к любой другой конечной точке hiapi) возвращает:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: <id>",
    "request_id": "<id>",
    "type": "hiapi_error"
  }
}

HTTP-статус — 401. Если ваш фреймворк или SDK не раскрывает исходный ответ, он может переупаковать это в обобщённое сообщение "API key(s) data are invalid", "unauthorized" или "invalid credentials" — но первопричина на стороне hiapi всегда одна и та же: 401.

Частые причины (по убыванию вероятности)

1. Неверное значение ключа. Обрезанная при копировании вставка, лишний пробел или копирование из старых заметок вместо актуального ключа из Dashboard → API Keys — всё это вызывает именно эту ошибку: независимо от того, искажён ключ, пуст или вообще не существует, hiapi возвращает абсолютно одинаковое сообщение.
2. Плейсхолдер ключа так и не был заменён. Код, скопированный из руководства или шаблона, часто содержит буквальную строку вроде sk-your-api-key — она даёт точно такой же 401, как и случайная строка.
3. Ключ был перевыпущен или отозван. Создание нового ключа в панели управления не аннулирует старый автоматически, но ручной отзыв или перегенерация — да; если какое-то развёртывание всё ещё ссылается на старое значение (не обновлённая переменная окружения, не перезагруженный .env), каждый запрос будет получать 401.
4. Ключ отправляется в неправильном заголовке. hiapi читает ключ только из заголовка Authorization. Отправка его как x-api-key, api-key или в параметрах запроса даёт тот же ответ permission_denied, потому что в этом случае hiapi не видит неправильно оформленный ключ — он просто вообще не видит ключ.
5. Переменная окружения пуста во время выполнения. Если ваш процесс читает переменную с ключом до загрузки файла .env, он отправляет в качестве ключа пустую строку — снова 401.
6. В ключ попали скрытые пробелы или символы новой строки. Это коварно: передача секрета через конвейер echo в shell-скрипте добавляет символ новой строки в конец значения. Если он попадает в заголовок Authorization, запрос ломается иначе — не чистый 401, а 400 с искажённым сообщением invalid json body, поскольку повреждённый заголовок просачивается в тело запроса. Если ваша ошибка выглядит как некорректно сформированный запрос, а не как чистый "invalid key", сначала проверьте ключ на наличие лишних пробелов или символов новой строки.

Исправление по шагам

1. Откройте Dashboard → API Keys и скопируйте ключ заново. Не используйте повторно значение из истории терминала или сообщений — копируйте прямо со страницы.
2. Убедитесь, что формат заголовка точно совпадает: Authorization: Bearer YOUR_API_KEY. Если вы собираете это значение в shell-скрипте, используйте printf, а не echo — echo добавляет в конец символ новой строки, который printf не добавляет.
3. Выведите значение перед отправкой запроса (console.log, print или отладочный лог), чтобы убедиться, что оно не пустое и не содержит лишних кавычек, пробелов или символов новой строки.
4. Проверьте ключ изолированно от вашего приложения с помощью обычного вызова curl (см. ниже). Если curl работает, а ваше приложение всё равно падает, то баг в том, как ваше приложение строит запрос, а не в самом ключе.
5. Проверьте фактический HTTP-статус, который вы получаете. 401 — это именно эта ошибка. 402 означает, что баланс аккаунта пуст, а не что ключ неверен. 403 означает, что ключ действителен, но у него нет прав на эту конкретную модель. 429 означает, что вы достигли ограничения скорости. Ни один из этих трёх случаев не следует считать проблемой недействительного ключа.

Минимальный пример проверки

Выполните следующую команду напрямую (подставив свой реальный ключ), чтобы убедиться, что проблема в самом ключе:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "input": {"prompt": "a small red apple on a white background"}}'

Рабочий ключ сразу вернёт ID задачи:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Неверный ключ вернёт 401, показанный выше. Если curl вернул ответ с taskId, а ваше приложение всё равно выдаёт ошибку "invalid key", то проблема в коде вашего приложения, который строит запрос, а не в ключе.

Связанные материалы

• Authentication docs — полный формат заголовка, руководство по перевыпуску ключей и справочник по кодам состояния.
• Dashboard → API Keys — место, где создаются, копируются и отзываются ключи.
• Rate limits — разница между 429 и 401 и условия их возникновения.
• Quickstart — если вы настраиваете hiapi впервые, здесь есть полная пошаговая инструкция для первого запроса.

Часто задаваемые вопросы

"invalid API key" и ограничение скорости — это одно и то же? Нет. 401 permission_denied означает, что сам ключ не принят. 429 с error_code: "RATE_LIMITED" означает, что ключ в порядке, но запросы приходят слишком быстро — пороговые значения см. в документации по ограничениям скорости.

Я только что создал новый ключ, но он всё равно не работает — почему? Убедитесь, что новый ключ действительно скопирован туда, откуда отправляется запрос. Новый ключ в панели управления не исправит автоматически жёстко заданное старое значение, неустановленную переменную окружения или не переразвёрнутый файл конфигурации.

Требует ли hiapi буквальное слово "Bearer" в заголовке? Документированный и поддерживаемый формат — Authorization: Bearer YOUR_API_KEY — всегда используйте его. Не полагайтесь на какое-либо снисходительное поведение, которое вы могли наблюдать в тестах; недокументированное поведение может измениться без уведомления.

Почему curl работает, а моё приложение — нет? Если curl с тем же ключом успешен, значит ключ действителен, и проблема в том, как ваше приложение собирает запрос — обычно это отсутствующий в коде префикс Bearer , чтение переменной окружения до загрузки .env или передача ключа в неправильный параметр в библиотеке-обёртке.

Что означает error.type: "hiapi_error"? Это универсальный конверт ошибок hiapi, который используется как для этого сбоя аутентификации, так и для других ошибок запросов. Проверяйте error.code (здесь это permission_denied), чтобы узнать фактическую ошибку, а не только тип конверта.