Как проверить API через curl — 6 команд, чтобы понять, чья это ошибка

Приложение не получает ответ от API. И начинается: console.log через строчку, перезапуск сервера, «может, я не так await поставил».
Полчаса в своём коде — и только потом выясняется, что сервер всё это время отвечал «неверный ключ».
Есть способ узнать это за тридцать секунд. Одна команда в терминале, мимо твоего кода целиком.
Зачем curl, если можно просто запустить приложение
Потому что в приложении между тобой и сервером стоит десяток слоёв: фреймворк, обёртка, кэш, переменные окружения, твоя логика. Ошибка может родиться в любом из них — а выглядит одинаково.
curl убирает все слои. Он берёт адрес и стучится напрямую. Ответ, который ты видишь, — это буквально то, что сказал сервер.
И у тебя сразу развилка:
- curl отвечает нормально → сервер жив, ключ рабочий, дело в твоём коде.
- curl отвечает ошибкой → твой код ни при чём, чини запрос или доступ.
Ставить ничего не нужно. curl идёт в комплекте с macOS, Linux и Windows 10+.
Шесть команд по порядку
1. Просто постучаться
curl https://api.github.com/users/torvalds
Если в ответ приехал JSON — связь есть. Пустота или ошибка сети — дальше идти незачем, проблема не в коде.
2. Посмотреть заголовки, а не только тело
curl -i https://api.github.com/users/torvalds
Флаг -i подмешивает к ответу служебную часть. Там живёт самое полезное: код ответа (HTTP/2 200), лимиты запросов (x-ratelimit-remaining) и идентификатор запроса, который попросит поддержка, когда ты придёшь ругаться.
3. Добавить ключ
Ключ передаётся заголовком через -H. Только не вписывай его в команду руками — положи в переменную окружения:
export API_KEY="твой-ключ"
curl -i https://api.openai.com/v1/models -H "Authorization: Bearer $API_KEY"
Ответ 401 — ключ не принят. 403 — ключ принят, но прав не хватает. Разницу между этими двумя стоит различать: 401 и 403 — это разные диагнозы.
4. Отправить POST с JSON
Самый частый запрос к модели выглядит так:
curl -s https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.6","messages":[{"role":"user","content":"Скажи «работает»"}]}'
Три вещи, на которых спотыкаются чаще всего:
-d— тело запроса. Как только в теле появляется-d, curl сам переключается на POST.- Заголовок
Content-Type: application/jsonобязателен, иначе сервер решит, что ты прислал форму. - Кавычки. Внутри JSON — двойные, снаружи — одинарные. Если путаешься, положи тело в файл и передай
-d @body.json.
5. Проверить стрим
Если ответ должен печататься по буквам, добавь в тело "stream": true, а к команде — флаг -N:
curl -N -s https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.6","stream":true,"messages":[{"role":"user","content":"Считай до пяти"}]}'
-N выключает буфер: без него curl копит ответ и вываливает разом, и ты не поймёшь, работает ли стриминг вообще. С ним в терминал побегут строчки data: {...} — это и есть поток.
6. Узнать только код ответа
Когда тело не нужно, а нужен вердикт:
curl -s -o /dev/null -w "%{http_code}\n" https://мойсайт.ru
-o /dev/null выбрасывает тело, -w печатает только код. Удобно, когда проверяешь десяток адресов подряд или хочешь понять, жив ли твой сервис после деплоя.
Трюк, который экономит больше всего времени
Собирать длинную команду руками не надо. Браузер умеет отдавать её готовой.
Открой DevTools → вкладку Network → сделай действие на странице → правый клик по нужному запросу → Copy → Copy as cURL.
В буфере окажется полная команда со всеми заголовками, куками и телом — ровно тот запрос, который отправил браузер. Вставляешь в терминал и играешь: убери заголовок, поменяй поле, повтори. Так за минуту находится тот единственный заголовок, без которого сервер сердится.
Ловушка: ключ уезжает в историю
Всё, что ты набрал в терминале, оседает в файле истории. Ключ, вписанный прямо в команду, остаётся там навсегда — и утекает вместе с бэкапом, скриншотом или демонстрацией экрана.
Поэтому и был export API_KEY=... в третьем шаге: в команде видно только имя переменной. Заодно так не получится случайно вставить ключ в чат или issue на GitHub. Остальные правила — в разборе, как безопасно хранить API-ключи.
Что получится
После шести команд у тебя на руках вот что:
- ты знаешь код ответа сервера — а значит, знаешь, куда смотреть;
- ты видел живой ответ и можешь сверить с ним то, что ждёт твой код;
- ты можешь дать эту же команду коллеге или в поддержку — она воспроизводится у любого.
Дальше правило простое: сначала curl, потом код. Тридцать секунд вместо получаса.
Чем curl отличается от Postman?
Ничем по сути — оба отправляют один и тот же HTTP-запрос. Разница в форме: у Postman окошки и история, у curl — одна строчка, которую можно скинуть в мессенджер, вставить в скрипт или в CI. Для быстрой проверки «жив ли сервер» curl обычно быстрее, потому что не надо ничего открывать.
Почему curl работает, а из кода тот же запрос падает?
Значит, различие в самом запросе, и его надо найти. Чаще всего это заголовки: код добавляет свои, curl — нет. Второй кандидат — тело: где-то объект превратился в строку не так, как ты думал. Третий, если запрос идёт из браузера, — CORS: curl на него не смотрит, а браузер режет ответ, даже когда сервер ответил 200.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





