Як уникнути CORS-помилок під час запитів до API

Чому запити до API падають через CORS і як це ламає продукт

Помилка CORS майже ніколи не приходить як зрозуміла діагностика — браузер просто блокує відповідь, а в консолі залишається сухий рядок про відсутній заголовок.

Для продукту це виглядає інакше: форма входу «крутиться» без відповіді, кошик не підтягує залишки, інтеграція із зовнішнім сервісом мовчки повертає порожнечу.

Користувач вважає, що сервіс зламано, хоча бекенд відпрацював коректно й повернув дані — їх відкинув браузер на етапі перевірки політики джерела.

Другий типовий збій — відхилений попередній запит. Браузер перед «складним» запитом до API окремо запитує в сервера дозвіл, і якщо у відповіді немає потрібних заголовків, до самого виклику справа не доходить.

Звідси класична картина: у тестовому середовищі все працює, а на проді запити до API падають, бо політику джерела налаштовано під конкретний домен і вона не враховує бойову адресу або піддомен.

Розбіжність середовищ за налаштуванням CORS — найдорожча категорія таких збоїв: вона не відтворюється локально й випливає вже в клієнта.

Ціна питання не в самій помилці, а в тому, як її шукають. Поки команда з'ясовує, справа в сервері, проксі чи фронтенді, реліз стоїть, а частина користувачів іде. Розбираємо, як налаштування CORS закривається на рівні конфігурації, щоб такі відмови не доходили до продакшену.

Що дає коректне налаштування CORS: ефект у цифрах

Коректне налаштування CORS прибирає цілий клас відмов, який інакше спливає вже у проді: браузер блокує запит, фронтенд отримує порожню відповідь замість даних, а в логах бекенду при цьому чисто — запит до сервера просто не доходить.

Діагностика такого інциденту займає години, бо симптом видно лише в консолі браузера в конкретного користувача, а не в моніторингу API. Коли політику описано явно — списком дозволених джерел, методів і заголовків, — цей сценарій перестає існувати як клас.

Час інтеграції скорочується передбачувано.

Поки правила роздаються навмання — «дозволимо все зірочкою, потім розберемося», — кожне нове середовище, піддомен або окремий клієнт перетворюється на окремий раунд відлагодження: розробник фронтенду та інженер бекенду по черзі перевіряють, чий заголовок не дійшов.

Узгоджена політика знімає ці ітерації: нове джерело додається однією правкою конфігурації, а не розслідуванням.

Стабільність API зростає завдяки тому, що дозволи перестають бути загальними. Точкові правила не пускають на бекенд сторонні джерела, а попередні запити кешуються браузером — повторні звернення до тих самих ручок ідуть без зайвого кола узгодження. Це помітно на навантажених екранах, де один рендер тягне десяток запитів.

Випуск релізів прискорюється, бо перевірка політики стає частиною звичайного контуру: правила лежать у репозиторії поруч із кодом, проходять рев'ю та розкочуються разом із застосунком.

Ніхто не править їх руками на бойовому контурі в момент викладки, а відкат повертає і код, і налаштування одразу.

Саме на стику цих ефектів — менше інцидентів, менше ручної роботи, рівніші релізи — і видно, що налаштування CORS це не формальність, а частина відмовостійкості продукту.

Підходи до налаштування CORS: порівняння варіантів

Налаштування CORS — це завжди вибір точки, у якій застосунок отримує дозвільні заголовки. Їх можна віддавати на самому сервері API, підставляти на проміжному шарі або зняти питання архітектурно, щоб браузер взагалі не бачив крос-доменний запит.

Нижче — чотири робочі варіанти, між якими реально обирають на проєктах, з чесними обмеженнями кожного.

Дозвільні заголовки на сервері — базовий варіант: він дає точний контроль над тим, яким доменам і з якими методами дозволено запити, і коректно працює із сесійними cookie.

Проксіювання виручає, коли чужий API не можна чіпати: запит іде на ваш домен, а сервер уже пересилає його далі — браузер бачить звичайний запит без крос-доменної перевірки.

API-шлюз має сенс, коли сервісів більше одного: правила доступу описуються один раз і застосовуються до всіх, а не розповзаються по конфігураціях. Ручне редагування заголовків годиться лише як тимчасове рішення — воно не переживає зростання команди й перший же рефакторинг.

На практиці вибір залежить від того, кому належить API і скільки середовищ потрібно підтримувати. Розберімо вашу схему запитів — повернемося з оцінкою, який варіант закриє завдання без зайвого шару.

Етапи впровадження: від аудиту запитів до передачі регламенту

Налаштування CORS — це не одна правка в конфізі сервера, а послідовність кроків, де кожен наступний спирається на попередній. Якщо пропустити аудит і одразу виставити заголовки, частина запитів відвалиться, а частина залишиться відкритою ширше, ніж потрібно. Тому ведемо роботу за етапами з перевіркою на кожному.

1. Аудит запитів. Збираємо всі джерела, з яких фронтенд звертається до API: домени, піддомени, локальні адреси розробників, сторонні віджети. Фіксуємо методи, заголовки та сценарії з обліковими даними — саме вони найчастіше ламаються при невірній політиці.
2. Проєктування політики. Визначаємо, які джерела допускаємо явно, які методи та заголовки дозволяємо, чи потрібні облікові дані та як обробляємо попередні запити. Замість шаблону «дозволити всім» отримуємо список правил під реальні сценарії.
3. Налаштування. Переносимо правила на сервер і в проміжний шар: заголовки відповіді, обробка попередніх запитів, кешування дозволів. Окремо перевіряємо, що політика не конфліктує з проксі та балансувальником.
4. Перевірка сценаріїв. Прогоняємо реальні ланцюжки: вхід, завантаження файлів, запити з обліковими даними, звернення зі сторонніх доменів. Дивимося, що дозволене проходить, а заборонене відхиляється з зрозумілою помилкою.
5. Документування. Описуємо чинні правила, причини кожного дозволу та порядок додавання нового джерела — щоб наступна правка не перетворювалася на археологію.
6. Передача. Віддаємо регламент команді, фіксуємо відповідальних і точки контролю. Політика стає частиною процесу, а не разовим патчем.

Такий порядок прибирає клас помилок, коли браузер блокує запит, а причина неочевидна. Опишіть задачу — повернемося з оцінкою та планом за етапами.

Що замовник отримує на руки: конфігурації та регламенти

Проєкт закривається не презентацією, а набором артефактів, за якими інший інженер зможе підняти середовище й повторити налаштування без нас. Нижче — що саме передаємо за підсумками робіт над веб-застосунком та його взаємодією із зовнішніми сервісами.

• Файли конфігурації — робочі конфіги для кожного середовища (розробка, тест, продуктив) з явним списком дозволених джерел, методів і заголовків. Окремо фіксуємо, які значення задаються змінними середовища, а які вшиті усвідомлено.
• Схеми взаємодії — діаграми потоків запитів між фронтендом, бекендом і зовнішніми API: хто ініціатор, де проходить попередній запит, на якому вузлі спрацьовує політика доступу.
• Політики доступу — правила, за якими домен потрапляє до білого списку, порядок додавання нового джерела та вимоги до його перевірки. Це знімає ситуацію, коли правку вносить перший, хто дістався до конфіга.
• Інструкції з розгортання та відкату — покроковий порядок застосування змін із точками повернення: якщо нова політика ламає інтеграцію, відкат займає хвилини, а не години пошуку причини.
• Чек-листи перевірки — набір сценаріїв, які проганяються перед викладкою: запит із дозволеного домену, з чужого, попередній запит, запит з обліковими даними. Кожен пункт — з очікуваним результатом.
• Регламент реагування — що робити, коли в браузері користувача з'являється помилка доступу: які дані зібрати, де дивитися журнали, кому ескалувати.
• Журнал змін політик — хто, коли і навіщо розширив список джерел. Через пів року це єдиний спосіб зрозуміти, чому відкрито доступ тому чи іншому домену.

Комплект розрахований на те, що команда замовника веде проєкт сама: конфігурації читабельні, схеми відображають реальний стан, чек-листи відтворювані. Опишіть вашу задачу — повернемося з оцінкою та планом, у якому обсязі ці артефакти закривають ваш контур.

Кейс: як ми усунули збої запитів і прискорили випуск

Клієнт — сервіс з особистим кабінетом і мобільним застосунком — прийшов із симптомом, який команда не могла зловити місяцями: частина запитів до API падала з помилкою політики безпеки браузера, але лише в половини користувачів і лише в проді.

На стенді все працювало, у розробників — теж. Відтворюваність нульова, а скарги в підтримку зростали.

Що знайшли

Причина виявилася складеною. Зворотний проксі віддавав різні заголовки для запитів з Origin і без нього, а попередній запит OPTIONS на частині маршрутів ішов у застосунок замість проксі й повертав редирект — браузер такої відповіді не приймає й блокує основний запит.

Плюс список дозволених джерел був захардкоджений у коді й не покривав новий піддомен, який додали під акції. Окремо кожен фактор нешкідливий, разом — плаваючі збої.

Що змінили

Ми винесли політику в конфігурацію проксі: єдиний список джерел, явна обробка OPTIONS до потрапляння в застосунок, коректний набір Access-Control-Allow-Methods і Access-Control-Allow-Headers під реально використовувані методи й заголовки.

Для запитів з обліковими даними зафіксували конкретні джерела замість шаблону — браузер не приймає широкий шаблон разом із передачею сесійних даних. Окремо закрили кешування попередніх відповідей, щоб правки політики застосовувалися без очікування.

Метрики до і після

Окремий ефект — передбачуваність випуску. Раніше будь-яка правка доменів або заголовків тягла за собою реліз застосунку й ручну перевірку, тепер це зміна конфігурації, яка проходить рев'ю й відкочується одним рядком. Команда перестала боятися чіпати інтеграції.

Ми працювали в зв'язці з їхнім Cloudflare і внутрішнім проксі, не змінюючи архітектуру застосунку: правки лягли на рівень, де їм і місце. Якщо у вас схожа картина — збої «то є, то немає» і довгий шлях будь-якої правки до проду — опишіть задачу, повернемося з оцінкою та планом.

Чим відрізняється налаштування CORS на сервері та на шлюзі?

На сервері політику задає сам застосунок: заголовки Access-Control-Allow-Origin, Allow-Methods, Allow-Headers формуються в обробнику або middleware і надсилаються в кожній відповіді.

Це дає максимальну гнучкість — правила можна будувати на даних запиту: пропускати конкретне джерело лише для певних маршрутів, підставляти різні набори методів для читання й запису, вести журнал відмов поруч із бізнес-логікою.

Обмеження одне: політика живе всередині коду, і за кількох сервісів її доводиться описувати в кожному, ризикуючи отримати розбіжності між ними.

Шлюз виносить ту саму політику на рівень перед застосунками. Правила описуються декларативно й застосовуються до всіх маршрутів одразу, однаково, незалежно від того, на чому написаний сервіс.

Попередній запит OPTIONS обробляється на вході й до застосунку не доходить — бекенд не витрачає ресурси на службові виклики.

Зворотний бік: шлюз бачить лише зовнішній контур запиту й не знає внутрішньої логіки, тому тонкі правила на кшталт «джерело A — лише для читання, джерело B — лише для запису» на ньому виражаються грубіше.

Ключова відмінність — у точці застосування політики. На сервері вона є частиною застосунку й змінюється разом із релізом; на шлюзі це конфігурація інфраструктури, яку правлять окремо від коду й розгортають централізовано.

Звідси й різна ціна помилки: неправильний заголовок у коді виправляється новим деплоєм сервісу, неправильне правило на шлюзі — правкою конфігурації без перезбирання застосунків.

Вибір залежить від контуру. Один сервіс із кількома джерелами — серверний варіант простіший і точніший. Кілька сервісів за спільним входом — шлюз прибирає дублювання й тримає єдиний стандарт.

Часто застосовують обидва рівні: шлюз закриває спільний периметр і службові запити, а застосунок доналаштовує правила під свої маршрути.

Часті технічні сумніви при налаштуванні CORS

Перш ніж змінювати заголовки відповідей, варто зрозуміти: CORS — це не «налаштування на сервері», а узгоджений контракт між джерелом запиту та API.

Більшість сумнівів виникає там, де фронтенд і бекенд правлять свої частини незалежно й перевіряють результат лише в браузері — за фактом появи помилки в консолі.

Як уникнути конфліктів між проксі, застосунком і зовнішнім сервісом?

Тримати одне джерело істини: список дозволених джерел задається в одному місці, інші шари його лише пробрасовують, не дописуючи свої значення. Якщо API віддає дані стороннім сайтам, політика описується окремо й явно — інакше перший же доданий домен ламає решту. Конфлікти майже завжди стежать за дублюванням правил, а не за їхнім змістом.

Як перевіряти, що налаштування справді працює?

Автотест на попередній запит із реальними джерелами й методами — він ловить регрес раніше, ніж користувач. Плюс перевірка з браузера з чистим профілем і з командного рядка: вони показують різні шари. Окремо фіксуємо поведінку при відмовах — яку відповідь отримує клієнт, коли джерело не дозволено.

Що робити з уже працюючими інтеграціями при зміні політики?

Вводити зміни поетапно: спочатку розширюємо список, спостерігаємо за зверненнями, лише потім прибираємо зайве. Логи запитів із відхиленими джерелами дають точну картину, хто ще ходить до API. Так перебудова проходить без раптових відмов у суміжних команд.

Якщо щодо вашої ситуації залишилися питання — опишіть поточну схему: де стоїть API, хто до нього звертається і як зараз влаштована перевірка. Повернемося з розбором і планом правок.

Обговоримо ваше завдання та повернемося з оцінкою й планом

Щоб повернутися з оцінкою та планом, а не із загальними словами, нам потрібен контекст завдання.

Налаштування CORS майже ніколи не зводиться до одного заголовка у відповіді сервера — важливо, звідки надходять запити, які методи та заголовки реально використовуються, чи є авторизація через cookie, скільки доменів і піддоменів задіяно. Чим точніше ви опишете картину, тим менше ітерацій піде на узгодження.

Опишіть завдання у вільній формі — цього достатньо для старту:

• які домени та піддомени звертаються до вашого API (фронтенд, мобільний застосунок, партнерські інтеграції);
• які методи потрібні: лише читання чи ще запис, видалення, попередні запити;
• чи передаються облікові дані — cookie, токени в заголовках, сесії;
• де зараз виникає помилка: у браузері, у логах сервера, лише в частини користувачів;
• який стек на фронтенді та бекенді, хто відповідає за конфігурацію сервера й зворотного проксі;
• чи є обмеження: вимоги безпеки, регламенти, заборона на правки в чужому сервісі.

Ми вивчимо контекст, відтворимо поведінку на вашій схемі запитів і запропонуємо рішення — з планом робіт, строками та тим, що потрібно з вашого боку.

Якщо завдання вирішується точковим правленням політики, скажемо прямо; якщо потрібна переробка схеми доступу, теж позначимо чесно, без нав'язування зайвого обсягу.

Обговоримо завдання — напишіть у зручному каналі, додайте приклади запитів і відповідей, якщо вони є. Повернемося з оцінкою та планом.