API-ключ не работает — чеклист из 3 причин, которые ловят всех

Ты получил ключ к API, вставил, запустил — и в ответ 401 Unauthorized или invalid API key. Ключ вот он, прямо перед глазами, выглядит правильным. А сервис говорит «не знаю такого».

Хорошая новость: причин почти всегда три, и все банальные. Сейчас пройдём их сверху вниз — от самой частой. В 9 случаях из 10 дело решится на первом шаге.

Причина 1 (самая частая): ключ не подхватился или с опечаткой

Чаще всего проблема не в ключе, а в том, как он до кода доехал. Лишний пробел в начале, случайные кавычки, невидимый перенос строки при копировании — и сервис видит уже не тот ключ. Или ты исправил ключ в файле .env, но приложение всё ещё держит в памяти старое значение.

Как проверить. Не печатай ключ целиком (это секрет), но распечатай его длину и пару первых-последних символов: совпадают с тем, что в панели сервиса? Часто сразу видно лишний пробел или что подставился вообще пустой текст.

Как починить. Пересоздай переменную окружения заново — аккуратно, без пробелов и кавычек вокруг значения. Затем перезапусти приложение или сервер: переменные читаются при старте, на лету они не обновляются. Ещё частая ловушка — перепутать тестовый и боевой ключ (test vs live): проверь, что взял нужный.

Причина 2: ключ передаётся не туда

Ключ правильный, но ты кладёшь его не в то место или не в том виде. Один сервис ждёт его в заголовке Authorization: Bearer ТВОЙ_КЛЮЧ, другой — в x-api-key: ТВОЙ_КЛЮЧ, третий — параметром в адресе. Перепутал формат — и сервис тебя не узнаёт, хотя ключ верный.

Особенно часто забывают слово Bearer перед ключом или ставят ключ в адрес запроса вместо заголовка.

Как проверить. Открой документацию сервиса, раздел Authentication: там дословно показано, в каком заголовке и в каком формате передавать ключ. Сравни со своим запросом по буквам.

Как починить. Самый надёжный путь — использовать официальный SDK сервиса: он сам ставит ключ в правильный заголовок, и эта причина отпадает целиком. Если SDK нет — приведи заголовок ровно к тому, что в доке.

Причина 3: с ключом проблема на стороне сервиса

Бывает, что ключ верный и передан правильно, но сам он «нерабочий»: не активирован, отозван, на счёте кончились деньги, не подключён нужный продукт или ты упёрся в лимит запросов (тогда код будет 429, а не 401).

Как проверить. Зайди в панель сервиса, найди свой ключ. Там виден его статус: активен ли, к какому проекту привязан, есть ли баланс, не истёк ли срок. Заодно глянь, включён ли нужный сервис для этого ключа.

Как починить. Активируй ключ, пополни баланс, включи нужный продукт — что именно, подскажет статус. Если ключ отозван или «протух» — просто выпусти новый и подставь его (не забудь перезапустить приложение, см. причину 1).

Я случайно закоммитил ключ в GitHub — что делать?

Считай его скомпрометированным, даже если репозиторий приватный. Немедленно отзови (revoke) этот ключ в панели сервиса и выпусти новый. Удалить коммит мало — ключ уже мог попасть в чужие руки. На будущее держи ключи только в .env и храни их безопасно.

Ключ в .env, но не читается — почему?

Пройди короткий чеклист: файл .env лежит в корне проекта? Имя переменной в файле точно совпадает с тем, что ждёт код (регистр важен)? Сервер перезапущен после правки? И не подменил ли значение случайный пробел или кавычки? Эти четыре вопроса закрывают почти все «не читается».