К содержимому
Блог

Как разобраться с ошибкой авторизации API-ключа

Как разобраться с ошибкой авторизации API-ключа

При ошибке авторизации сначала проверьте, какой ключ и заголовок фактически использует клиент. Наличие секрета в настройках терминала ещё не означает, что запущенный редактор или сервер получил это значение.

Проверьте окружение процесса

Приложение читает переменные своего процесса. Если ключ добавлен после запуска сервера, перезапустите этот сервер штатным способом. Для редактора проверьте его собственное поле ключа. Настройки дочернего терминала и графического приложения могут расходиться.

Наличие переменной можно проверить без вывода секрета:

bash
if test -n "${RELAY_API_KEY:-}"; then
  printf 'RELAY_API_KEY задана\n'
else
  printf 'RELAY_API_KEY отсутствует\n'
fi

Не заменяйте проверку командой echo "$RELAY_API_KEY" при демонстрации экрана. Передача секрета в логи создаёт новую проблему, даже если ошибка подключения быстро исправлена.

Проверьте длину ключа

На 14 октября 2026 года ключ Relay начинается с sk-rly- и занимает 47 знаков. Пробелы и переводы строки по краям значения шлюз отбрасывает сам. Символ внутри ключа, например разрыв строки при копировании из чата, ломает проверку длины или контрольной суммы, и приходит 401. Длину можно узнать, не показывая ключ:

bash
printf '%s' "$RELAY_API_KEY" | wc -c

Больше 47 значит, что в значение попали лишние знаки: чаще всего перевод строки после вставки из чата или пробел после = в файле .env. Меньше 47 значит, что ключ обрезан при копировании. Задайте переменную заново и вставьте ключ целиком.

Сверьте заголовок и адрес

Форма Bearer: Authorization: Bearer и значение ключа после пробела. В Relay также предусмотрен заголовок x-api-key; форму для выбранного клиента смотрите в руководстве авторизации.

Если библиотека принимает отдельный параметр api_key, передайте туда сам ключ. Не дописывайте Bearer к значению этого параметра: библиотека формирует заголовок самостоятельно. Base URL для OpenAI-совместимого SDK: https://relay-llm.ru/v1.

Проверьте пару «ключ и адрес»

Ключ другого сервиса, присланный на адрес Relay, получает 401: формат не пройдёт проверку. То же верно в обратную сторону, ключ Relay на чужом адресе не примут. Верный ключ с неверным адресом даёт другой результат. OpenAI-клиенту нужен адрес https://relay-llm.ru/v1, а Anthropic SDK получает корень https://relay-llm.ru и сам добавляет /v1/messages. Если дописать лишнее /v1, шлюз ответит 404 not_found. Если /v1 забыть, запрос попадёт не в шлюз, а на страницы сайта, и вместо JSON-ошибки вы получите ответ сайта. В обоих случаях это не 401, и по этой разнице видно, что виноват адрес, а не ключ.

Если ошибка появилась не сразу, вспомните про срок жизни ключей. Удалённый или отключённый ключ перестаёт приниматься в течение минуты. После перевыпуска старый ключ работает льготный срок, который вы выбрали, а затем тоже получает 401.

Отделите ключ от прав доступа

Отозванный ключ нужно заменить в приложении. Если ключ активен, проверьте его ограничения и текущий аккаунт в кабинете. Ограничение доступа и ошибка авторизации требуют разных действий, поэтому ориентируйтесь на код ошибки, а не только на красное уведомление клиента.

Коды из одной группы легко перепутать, поэтому ниже они собраны вместе:

Статус и кодЧто значитЧто делать
401 invalid_api_keyключ не принят: не передан, неверный, отключён, удалён или просроченпроверить значение, заголовок и статус ключа
402 key_limit_exceeded, insufficient_balanceключ принят, но не хватает лимита ключа или балансаподнять лимит ключа или пополнить баланс
403 model_not_allowedключ принят, но эту модель ему использовать нельзяразрешить модель в настройках ключа
403 user_blockedаккаунт заблокированобратиться в поддержку
404 not_found, model_not_foundневерный путь или идентификатор моделипроверить адрес, взять идентификатор из каталога

Недостаточный баланс тоже не исправляется выпуском нескольких ключей. Проверьте причину в справочнике ошибок и остановите автоматические повторы до её устранения.

Подготовьте обращение в поддержку

Передайте время запроса с часовым поясом, имя клиента и его версию, протокол, идентификатор модели, HTTP-статус, код ошибки и request_id, если он есть. Не включайте Cookie, Authorization, полный URL с секретными query-параметрами или файл настроек целиком.

Если ключ уже попал в чат или публичный репозиторий, сначала отзовите его. Удаление сообщения не возвращает секрету безопасность. Новый ключ выпустите отдельно и повторите один короткий запрос по быстрому старту.

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.