Симптом: ключ скопирован из кабинета провайдера минуту назад, вставлен в настройки, сохранён — и приложение отвечает 401 Unauthorized или «invalid api key». Ключ при этом выглядит правильным.
В большинстве случаев он и есть правильный. Ломается не ключ, а одна из четырёх вещей вокруг него: содержимое строки, адресат, аккаунт или адрес запроса. Ниже — таблица кодов и процедура, которая находит причину за четыре шага.
#Быстрая проверка
Проверять нужно вне приложения — это отделяет проблему ключа от проблемы клиента:
curl -s -o /dev/null -w "%{http_code}\n" https://АДРЕС_ЭНДПОИНТА \
-H "Authorization: Bearer ВАШ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{"model":"ИМЯ_МОДЕЛИ","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'
Полученный трёхзначный код — вход в таблицу ниже. Если здесь приходит 200, а приложение всё равно ошибается, проблема в приложении, а не в ключе.
#Таблица: код → причина → проверка
| Код | Что означает | Первая проверка |
|---|---|---|
| 401 | ключ не принят | символы в строке, тот ли провайдер |
| 403 | ключ принят, доступ запрещён | регион, права ключа, доступ к модели |
| 404 | адрес или модель не найдены | путь эндпоинта, точное имя модели |
| 400 | запрос сформирован неверно | обязательные поля, формат тела |
| 402 или 429 | квота или баланс | раздел использования в кабинете |
| 5xx | сбой на стороне провайдера | страница состояния сервиса |
Главное, что видно из таблицы: 401 и 403 — разные диагнозы. При 401 сервис вас не узнал, при 403 узнал и отказал. Менять ключ во втором случае бесполезно: причина в правах, в регионе или в доступе к конкретной модели.
#Процедура диагностики за четыре шага
Шаг 1. Проверить содержимое строки.
Самая частая причина 401 при верном ключе — символы, которых вы не видите: пробел в начале или конце, перенос строки, неразрывный пробел, кавычки, приехавшие вместе с текстом из документации.
printf '%s' "$KEY" | wc -c
printf '%s' "$KEY" | od -c | tail -3
Первая команда даёт длину: сверьте её с длиной строки в кабинете провайдера. Вторая показывает каждый символ, включая \n и пробелы в конце.
В Windows PowerShell:
$key.Length
[int[]][char[]]$key | Select-Object -Last 5
Если в конце обнаружился код 10 или 32, ключ приехал с мусором. Лечение — очистить поле и вставить строку заново, а лучше набрать первые и последние символы вручную для контроля.
Шаг 2. Проверить, тому ли провайдеру вы его показываете.
Ключи узнаваемы по префиксу: sk-or- у OpenRouter, gsk_ у Groq, sk-ant- у Anthropic, csk- у Cerebras, AIza у Google. Ключ российского шлюза работает только с адресом этого шлюза, а не с адресом вендора, к которому шлюз обращается.
Сюда же относится формат заголовка: часть провайдеров ждёт Authorization: Bearer, часть — собственный заголовок вроде x-api-key. Где проходит граница совместимости между API разных вендоров, разобрано в материале про OpenAI-совместимый API.
Шаг 3. Проверить аккаунт и состояние ключа.
- Ключ не отозван и не истёк — откройте список ключей в кабинете.
- Вы смотрите тот аккаунт, в котором ключ выпущен: у людей с личным и рабочим входом это регулярная путаница.
- Баланс положительный, если у провайдера нет бесплатного уровня. Пустой баланс иногда отдаёт ошибку, похожую на проблему с ключом.
- Ключ не ограничен по проекту или по списку моделей так, что нужная модель в него не входит.
Шаг 4. Проверить адрес и имя модели.
Ошибка 404 приходит, когда путь эндпоинта отличается от ожидаемого: у части сервисов он нестандартный и не заканчивается на /v1. Имя модели должно быть скопировано из документации сервиса целиком, включая префикс вендора и суффиксы.
Если код 429 — дело не в ключе вовсе, а в лимитах; их разбор в статье про ошибку 429 и лимиты запросов.
#Если ничего не помогло
- Выпустите новый ключ. Это дешевле дальнейшей диагностики: пять минут против часа.
- Проверьте, не утёк ли старый. Если он внезапно перестал работать без ваших действий, возможно, его отозвал сам провайдер после обнаружения утечки. Признаки и порядок действий — в материале про хранение API-ключа и признаки его утечки.
- Проверьте, откуда уходит запрос. Регион определяется по адресу сервера, а не по вашему браузеру: ключ, работающий с вашего ноутбука, может получать 403 с сервера в другой стране.
- Убедитесь, что приложение использует именно этот ключ. Сохранённый ранее ключ другого провайдера — частая причина того, что правильная строка «не применяется». Пошаговый разбор экрана подключения — в инструкции про то, как подключить свою модель в Persona.
#Частые вопросы
#Можно ли посмотреть свой ключ в кабинете провайдера ещё раз?
Почти нигде нельзя: сервис хранит не саму строку, а её хэш, поэтому показать её повторно не может технически. Если ключ потерян, единственный путь — выпустить новый и заменить его во всех приложениях, где использовался старый.
#Почему ключ работал вчера, а сегодня возвращает 401?
Типичные причины: ключ отозван вручную или самим провайдером, истёк срок его действия, изменились права, аккаунт заблокирован или переключён на другую организацию. Список ключей в кабинете отвечает на этот вопрос за секунды.
#Чем отличается 401 от 403?
При 401 сервис не признал предъявленные учётные данные. При 403 он их признал, но отказал в действии: нет прав на модель, запрос из недоступного региона, ограничение ключа. В первом случае разбираются с ключом, во втором — с правами и регионом.
#Ключ верный, но приложение всё равно не подключается — что дальше?
Проверьте его командой из начала статьи. Если она возвращает 200, ключ и доступ в порядке, и дальше нужно смотреть на приложение: какой адрес оно использует, какое имя модели подставляет и не подхватило ли оно другой сохранённый ключ.
#Безопасно ли вставлять ключ в командную строку для проверки?
Строка попадает в историю оболочки, поэтому либо очищайте её после проверки, либо подставляйте ключ из переменной окружения. Для разовой диагностики удобнее выпустить временный ключ и отозвать его сразу после — общий обзор провайдеров и работы с ключами в статье о том, где взять ключ к языковой модели.