HTTP 402 vs 503 in x402 APIs: when should an agent pay?
Guides
A 402 response can carry current payment terms. A 503 response says the API is temporarily unavailable. Learn when an x402 client should stop, wait and retry.
For an x402 client, an HTTP status is a control signal. A non-success response is not automatically a request to pay. The client should read the current response from the exact origin and method before it creates a payment authorization.
HTTP 402 is the payment branch of the x402 flow when the response carries a valid PAYMENT-REQUIRED header or equivalent payment requirements in the body. The client can inspect the offered network, asset, amount, recipient and resource before choosing one complete option. The response is an offer of terms, not proof that a previous purchase was delivered.
HTTP 503 has a different meaning: the server is temporarily unable to handle the request. A Retry-After header can tell the client when to check again. The safe action is to stop before payment, preserve the request context and retry only after the stated delay or a later status check.
A robust client branches on the live response. On 503 it does not sign or attach payment data. On 402 it validates the exact resource, method and complete payment requirement before asking for spending approval. On any inconsistent response, such as temporary-unavailability status combined with stale payment terms, it stops and obtains a fresh response.
A marketplace row or cached discovery document cannot override the current origin. Before payment, compare the live API contract, the x402 discovery document and the public service status. If a listed route is paused or absent from the current contract, do not pay merely because an external directory still displays it.
Keep the response time, status, retry hint, selected payment requirement and later payment response as separate evidence. Settlement, execution and result delivery are later stages. This record lets an operator investigate one request without treating a temporary outage as a payment instruction.