Почему API возвращает 401 — и чем это отличается от 403: 3 причины

Дёргаешь API, а в ответ — 401 Unauthorized. Первая мысль: «мне запретили доступ». Вот что сразу экономит время: 401 значит не «тебе нельзя», а «я не понял, кто ты». Сервер тебя не узнал.

Разница тонкая, но она указывает направление. Код начинается на 4 — значит, виноват запрос, а не сервер. А слово «Unauthorized» здесь обманчиво: по смыслу это «не аутентифицирован» — то есть ключ или токен не долетел, долетел не так или протух. Разберём три причины, начиная с самой частой.

Симптом

Запрос к API падает со статусом 401 (в теле часто Unauthorized или invalid credentials). В DevTools → Network этот запрос горит красным с кодом 401. Важно: сервер ответил — он на месте и работает. Он просто не признал в тебе того, кому можно отвечать. Значит, дело в том, как ты представился, — в ключе или токене.

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

В большинстве случаев проблема не в самом ключе, а в том, как его передали. Забыли заголовок авторизации, ошиблись в его названии, не добавили слово Bearer перед токеном, склеили с лишним пробелом — сервер получает мусор и говорит «не узнаю».

Как проверить. Залогируй ровно то, что уходит на сервер, — заголовок Authorization целиком. Чаще всего окажется: там undefined, пусто или нет слова Bearer . Быстрый способ отделить свой код от ключа — дёрни тот же запрос через curl с ключом руками: заработало — баг в коде, всё равно 401 — дело в ключе.

Как починить. Большинство API ждут заголовок строго в форме Authorization: Bearer твой_ключ — проверь и название, и слово Bearer, и что ключ подставился (а не остался undefined из-за незагруженной переменной окружения). Убедись, что ключ вообще передаётся, а не теряется по дороге.

Причина 2: ключ протух, отозван или не из того окружения

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

Как проверить. Открой панель сервиса и глянь список API-ключей: активен ли, не отозван, не пересоздан. Если это токен сессии (JWT) — у него внутри есть срок годности; проверь, не в прошлом ли он. Признак истечения: «работало, потом резко перестало без изменений в коде».

Как починить. Перевыпусти ключ и подставь новый. Для токенов сессии — залогинься заново, чтобы получить свежий, и настрой обновление до истечения. И проверь, что берёшь ключ того окружения, куда стучишься: боевой ключ — на боевой адрес, тестовый — на тестовый.

Причина 3: не та схема авторизации

Реже, но бывает: ключ живой и передаётся, а API ждёт его иначе, чем ты шлёшь. Одни сервисы хотят Authorization: Bearer ..., другие — свой заголовок вроде x-api-key, третьи — ключ в параметре запроса. Шлёшь не туда — снова 401.

Как проверить. Открой доку API на разделе авторизации и сверь буквально: как называется заголовок, нужно ли слово Bearer, где вообще ждут ключ. Сравни с тем, что отправляешь ты.

Как починить. Приведи запрос ровно к тому, что в доке. Не угадывай формат — у каждого API он свой, и «обычно так» тут не работает. Один раз свериться с примером из документации быстрее, чем перебирать варианты.

Чем 401 отличается от 403?

Это про разные вещи. 401 (Unauthorized) — «я не знаю, кто ты»: credentials не пришли или неверны, ты не аутентифицирован. 403 (Forbidden) — «я знаю, кто ты, но тебе сюда нельзя»: ты вошёл, но прав на это действие нет. Грубо: 401 — покажи пропуск, 403 — пропуск есть, но дверь не твоя. Подробнее — в разборе аутентификации и авторизации.

Почему ключ работал вчера, а сегодня 401?

Почти всегда — истёк или отозван. Токены сессии живут недолго и умирают по расписанию; API-ключи иногда перевыпускают из панели, и старый разом перестаёт годиться. Раз код не менялся, а ответ сменился на 401 — первым делом обнови ключ или залогинься заново, а не ищи баг в запросе.

Может ли 401 быть виной сервера?

Крайне редко. Код на 4 по определению про запрос, а не про сервер, — 401 говорит «с твоими credentials что-то не так». Исключение — если у самого сервиса сбой авторизации на их стороне; тогда 401 ловят все, и это видно в статусе сервиса. Но в 99% случаев причина у тебя: ключ, его формат или срок.