HTTP 402 для API: як працює платний доступ для AI-агентів

Один запит о 03:17

Раніше платний доступ часто виглядав просто: людина відкрила сайт, побачила кнопку купівлі, ввела картку і свідомо натиснула оплатити. Для API така картина давно не завжди працює, а з AI-агентами стає ще менш очевидною. Запит може зробити агент о 03:17 ночі, без екрана, без кошика і без моменту, де користувач явно побачив суму.

Тому корисно думати не про красиву сторінку оплати, а про шлях одного HTTP-запиту. Платний ресурс має вміти сказати: ресурс існує, але зараз я його не віддам; ось умови; повернись із доказом оплати; тоді я перевірю не лише оплату, а й право доступу, ліміти та журнал подій.

Cloudflare у своєму Monetization Gateway описує свіжий приклад такого підходу на базі x402: сервер може відповідати HTTP 402 Payment Required, передавати умови, приймати повторний запит із proof of payment і після перевірки віддавати ресурс. Але головна ідея ширша за один сервіс: платний доступ має бути частиною операційного потоку, а не магічною кнопкою перед API.

Крок 1: перший запит до платного ресурсу

Уявімо, що AI-агент просить дорогий набір даних через API. Перший запит не повинен автоматично відкривати доступ лише тому, що в ньому є ключ API. Сервер або граничний вузол перевіряє, який ресурс запитано, хто клієнт, чи є в нього базова авторизація і чи потрібна оплата саме для цієї операції.

Якщо доступ платний, відповідь HTTP 402 має повернути зрозумілі умови: що коштує запит, яка одиниця обліку використання, який спосіб підтвердження приймається, скільки часу дійсна пропозиція. У журналі аудиту варто записати ідентифікатор клієнта, ресурс, час, ціну або тариф, причину 402 і кореляційний ідентифікатор для наступного запиту.

Анти-патерн тут простий: віддавати 402 без структурованих умов або змішувати його з помилками авторизації. Якщо клієнт не має права бачити ресурс узагалі, це не питання оплати. Спершу авторизація, потім умови платного доступу.

Крок 2: повторний запит із доказом оплати

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

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

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

Крок 3: фінальне рішення бекенду

Навіть після успішної перевірки оплати бекенд не має автоматично віддавати все. Авторизація залишається окремою перевіркою. Клієнт міг оплатити один набір даних, але не мати права читати приватні поля. Агент міг працювати від імені організації, але не мати дозволу на експорт. Платіж підтверджує економічну умову, а не всі правила безпеки.

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

Це допоможе під час спорів: клієнт каже, що заплатив, але не отримав дані; команда бачить, де саме потік зупинився.

Що не варто віддавати платіжному провайдеру

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

Окремо перевірте vendor lock-in. Якщо формат доказу, тарифи і правила доступу повністю прив’язані до одного edge-рішення, міграція стане дорогою. Краще описати внутрішній контракт: які поля потрібні бекенду, які події логуються, які рішення залишаються у вашій системі.

Практичний запуск без зайвої магії

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

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

Джерела

• Cloudflare: Monetization Gateway — https://blog.cloudflare.com/monetization-gateway/
• RFC 9110: HTTP Semantics, 402 Payment Required — https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-required
• Model Context Protocol — https://modelcontextprotocol.io/