HTTP 402 for APIs: how paid access works for AI agents

One request at 03:17

Paid access used to look simple in many products: a person opened a website, saw a purchase button, entered a card, and deliberately clicked pay. For APIs, that picture has long been incomplete. With AI agents, it becomes even less obvious. A request can be sent by an agent at 03:17, with no screen, no checkout page, and no clear moment where the user saw the cost.

So it is useful to think less about a payment page and more about the journey of one HTTP request. A payment-gated resource needs a way to say: the resource exists, but I will not return it yet; here are the terms; come back with proof of payment; then I will check not only payment, but also authorization, limits, and the event trail.

Cloudflare describes a recent example of this pattern in its Monetization Gateway, built around an x402-style flow: a server can respond with HTTP 402 Payment Required, return payment terms, accept a retry with proof of payment, and return the resource after verification. The broader lesson is not tied to one vendor. Paid access should be part of an operational flow, not a magic button placed in front of an API.

Step 1: the first request to a payment-gated resource

Imagine an AI agent requesting an expensive dataset through an API. The first request should not automatically open access just because it contains an API key. The server or edge layer checks which resource is requested, who the client is, whether basic authorization exists, and whether this exact operation requires payment.

If access is paid, the HTTP 402 response should return clear terms: what the request costs, what the metering unit is, what proof format is accepted, and how long the offer is valid. The audit log should record the client identifier, resource, time, price or tariff, reason for 402, and a correlation identifier for the next request.

The anti-pattern is simple: returning 402 without structured terms, or mixing it with authorization failures. If the client is not allowed to see the resource at all, that is not a payment question. First authorization, then the terms of paid access.

Step 2: the retry with proof of payment

After receiving 402, the client can make a payment or obtain another proof of payment. It then repeats the request and attaches that proof in the agreed format. For a human, this resembles coming back after checkout. For an agent, it is a machine step that must be constrained and predictable.

At this point, the system must not trust the proof just because it looks correct. It needs to verify a signature or payment state, expiry time, resource match, amount, client identity, and correlation identifier. If the proof of payment can be reused for another resource or another user, the team has created replay and fraud risk.

Rate limits matter here too. Without them, a malicious client can flood the system with retries containing invalid proofs, overload verification, or generate costly calls to a payment facilitator.

Step 3: the backend makes the final decision

Even after successful payment verification, the backend should not automatically return everything. Authorization remains a separate check. A client may have paid for one dataset but not be allowed to read private fields. An agent may act on behalf of an organization but not have export rights. Payment confirms an economic condition, not every security rule.

The final decision should consider: who the client is, which resource is requested, what action is being performed, what the metering unit is, whether the limit has been exceeded, whether access has been revoked, and whether there is an active incident. The audit log should include not only success, but also denials: invalid proof, expired proof, resource mismatch, exceeded limit, and authorization failure after payment.

That record becomes important in disputes. A client says they paid but did not receive data; the team can see exactly where the flow stopped.

What not to delegate to a payment provider

A payment or edge provider may be very good at checking proof of payment. But it should not become the only place where access rules live. The team is still responsible for the role model, data privacy, logs, refunds, disputed requests, budget controls, and dependency on one provider.

Check vendor lock-in separately. If the proof format, tariffs, and access rules are fully tied to one edge solution, migration becomes expensive. It is safer to define an internal contract: which fields the backend needs, which events are logged, and which decisions stay inside your system.

Launch without unnecessary magic

Start with a map of one request. Draw the client, payment-gated resource, verification node, backend, metering, rate limit, and audit log. For every arrow, ask: who trusts whom, what can be forged, what happens on replay, and what the support team can see.

HTTP 402 is useful because it gives this flow an explicit signal. It does not replace security, authorization, or spend control. But it gives an API a clear place to tell a machine client: access is possible, the terms are known, bring verifiable proof — and then we will make a separate operational decision.

Sources

• 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/