What Is 402 Status Code and When Does It Actually Matter

Most developers hit a 404 and know exactly what happened. They get a 500 and start sweating. But the 402 status code? Most people see it and just… pause. It’s one of those HTTP responses that technically exists in the spec, has a clear name, “Payment Required,” and yet sits in this weird gray zone where the official documentation basically says “yeah, we haven’t fully figured this one out yet.”

That’s not a knock on the HTTP spec. It’s actually honest. The 402 was defined way back in 1992 as part of the original HTTP/1.0 specification, reserved for future use related to digital payment systems that didn’t really exist yet. The idea was that someday, micropayment systems would take over the web, and servers would need a standard way to tell clients “you need to pay before you get this.” That future mostly didn’t arrive the way anyone expected. And so the 402 status code has spent decades being technically reserved, occasionally misused, and regularly misunderstood.

Here’s the thing though: developers are still running into this code in 2026, especially in API-heavy environments, SaaS platforms, and payment-gated content systems. Stripe uses it. Twilio uses it. A bunch of REST APIs you’ve probably worked with throw a 402 when your billing is off or your trial has expired. So while it may not be in the HTTP core like 200 or 404, it’s real and it shows up in production. You need to know what it means, why servers send it, and how to handle it properly in code.

TL;DR / Quick Summary

• The 402 status code means “Payment Required” and was reserved in 1992 for future digital payment use cases that never fully standardized.
• No official, universal behavior is defined for 402, which means implementations vary widely across APIs and platforms.
• Stripe, Twilio, and other API providers use 402 to signal billing issues like expired trials, failed charges, or exceeded usage limits.
• Handling a 402 in your application requires checking the response body, not just the status code, since the reason varies by provider.
• From an SEO standpoint, a 402 on a publicly indexed URL can hurt your crawl budget and block Googlebot from accessing content it previously ranked.
• If you’re designing an API, 402 is a valid choice for payment gating, but you need to pair it with a clear, machine-readable error body.

What the 402 Status Code Actually Means in HTTP

The 402 status code is an HTTP client error response in the 4xx range, meaning the problem is on the requester’s side, not the server’s. The name is “Payment Required.” Simple enough. The tricky part is that the HTTP specification deliberately left its exact behavior undefined, describing it as “reserved for future use.”

That’s still true today in RFC 9110, the current HTTP semantics document. There’s no mandated body format, no required headers, no defined behavior for what a client should do when it receives one. Compare that to 401, which has a clear challenge mechanism and defined headers like WWW-Authenticate. The 402 has none of that scaffolding. It’s like a room that was framed in the house but never furnished.

Why the 402 Was Created This Way

The original HTTP/1.0 specification from 1992 was written with a lot of optimism about where the web was going. One of the visions was a web economy built on micropayments, where you’d pay tiny amounts to read individual articles, run API queries, or access premium content. Tim Berners-Lee and the early web crowd thought this would be the natural model.

The 402 was pre-allocated for that payment layer. Developers figured they’d come back and define the exact mechanism once micropayment standards emerged. That standardization never happened in a cohesive way. PayPal came along, then credit card APIs, then Stripe, and each one built its own payment flow without needing a standardized HTTP response to drive it.

So we’re left with a status code that has a clear name, a sensible purpose, and zero official implementation details. That’s why you’ll find wildly different behavior across platforms that do use it.

How 402 Fits Into the HTTP 4xx Family

The 4xx range is all about client errors. The request made it to the server, the server understood it, but something about the request itself caused the problem. Here’s a quick look at the ones that live near 402:

• 400 Bad Request: The request was malformed. Syntax problem. Fix your request.
• 401 Unauthorized: You’re not authenticated. Send credentials.
• 402 Payment Required: You haven’t paid. (Behavior undefined, but that’s the intent.)
• 403 Forbidden: You’re authenticated but not allowed. Access denied.
• 404 Not Found: The resource doesn’t exist at this URL.

The 402 slot between 401 and 403 actually makes semantic sense. You’re authenticated (you’re not hitting a 401), but you’re not authorized to access this specific resource because of payment, not permissions (which is 403 territory). The problem is that without standard behavior, most developers default to using 403 for payment gating anyway, which muddies the water even further.

Where You’ll Actually See the 402 Status Code in Real APIs

Forget theory. Here’s where the 402 status code actually shows up in the wild.

Stripe and Payment Processor APIs

Stripe uses 402 in specific scenarios, though not as broadly as you might expect given the name. When a card charge fails at the payment processor level, certain Stripe endpoints return a 402 with an error object in the body. The response body matters here more than the status code itself.

A 402 from Stripe usually looks like this in the response body:

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "decline_code": "insufficient_funds"
  }
}

The 402 tells your code “payment failed.” The body tells you why. If you’re just checking for a non-200 response and moving on, you’re going to miss important details your user needs to see. Always read the body when you get a 402 from any payment-related API.

Twilio

Twilio throws a 402 when your account has insufficient funds to complete a billable action, like sending an SMS or making a call. This is one of the cleaner real-world implementations of the 402 concept: you’re authenticated, your request is valid, but you can’t execute it because payment capacity doesn’t exist on the account.

Their error response includes a Twilio-specific error code (code 20003 is the account not found or insufficient funds variant) so you can handle it programmatically. Again, check the body.

SaaS Trial Expiration and Usage Limits

A lot of SaaS APIs use 402 to signal that a free tier or trial has ended. You’ve authenticated fine, your request is properly formed, but the resource is now behind a paywall you haven’t crossed yet. Some examples:

• A content API returning 402 when you’ve hit your monthly API call limit on the free plan
• A video processing service returning 402 when your trial expires
• A data enrichment API returning 402 when you’ve exceeded your credit balance

This is probably the most common place developers in non-payment companies encounter the 402. You’re building on top of a third-party API, everything works during development on a free tier, and then your app starts throwing 402 errors in staging or production because you never accounted for hitting the limit.

GitHub Copilot and Developer Tool APIs

GitHub has used 402 in some of its API contexts for feature gating. If you’re hitting a GitHub API endpoint that requires an active subscription to a specific product and your account doesn’t have it, a 402 can appear. The pattern is the same: authenticated, valid request, but payment-gated.

Legacy Systems and Misconfigured Servers

Nope, not all 402s are intentional. Some older web applications and misconfigured servers throw 402 when they actually mean to send a 403 or even a 401. If you’re seeing a 402 on a resource that has nothing to do with payments, that’s likely a misconfiguration. The fix is on the server side, not yours.

How to Handle a 402 Status Code in Your Code

Okay so you’re getting a 402 back. What do you do? This depends on whether you’re consuming an API or building one.

Handling 402 as an API Consumer

First thing: don’t treat 402 like a 500 and retry automatically. This is a client error. Retrying won’t fix it because the problem isn’t transient. The server is telling you something needs to change on your end, specifically your payment status.

Here’s a sensible handling flow:

Step 1: Log the full response. Status code plus body. You need the body to understand what specifically failed. Just logging “402 received” is useless.

Step 2: Check if this is user-actionable or admin-actionable. A user’s card declining in your app is user-actionable. Your own API key running out of credits is admin-actionable. These require different responses.

Step 3: Surface the right message. Don’t show a raw 402 to end users. Parse the error body, translate it into something human: “Your payment method was declined. Please update your billing info.” Then link to where they can fix it.

Step 4: Handle it at the service layer, not the UI layer. If you’re using a third-party API internally, catch 402s in your service/repository layer and throw a typed exception your application can handle properly. Don’t let raw HTTP status codes bubble up to your frontend.

Here’s a basic example in JavaScript:

async function fetchProtectedResource(url, token) {
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` }
  });

  if (response.status === 402) {
    const errorBody = await response.json();
    throw new PaymentRequiredError(errorBody.message || 'Payment required');
  }

  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status}`);
  }

  return response.json();
}

Clean separation between the HTTP detail and your application logic. That’s the move.

Implementing 402 in Your Own API

If you’re building an API and you want to gate resources behind payment, the 402 is a legitimate choice. Here’s how to do it well.

Use a consistent error body format. Something like:

{
  "error": {
    "status": 402,
    "code": "payment_required",
    "message": "Your subscription has expired. Please renew to access this resource.",
    "payment_url": "https://yourapp.com/billing"
  }
}

Including a payment_url in the response body is a genuinely useful pattern. The client doesn’t have to know your billing URL in advance. The 402 tells them where to go.

Document it explicitly. If your API can return a 402, put it in your API docs with example responses. Developers consuming your API will thank you. The worst thing you can do is throw a 402 that nobody expected and leave them digging through support tickets trying to figure out why their integration broke.

Don’t use 402 for permission errors. If a user is on the wrong plan tier but it’s not a billing failure, use 403. Reserve 402 for situations where the literal problem is that money hasn’t changed hands or billing has actively failed.

The 402 Status Code and Its SEO Implications

This is where a lot of developers miss something. HTTP status codes aren’t just for your API consumers. They affect how search engines crawl and index your pages.

What Happens When Googlebot Hits a 402

Googlebot treats a 402 the same way it treats other 4xx errors: it can’t access the content. If a URL that was previously indexed starts returning a 402, Google will eventually drop it from the index. The timeline isn’t instant, but over several crawl cycles, pages returning 4xx responses lose their rankings.

For most developer tools and API documentation pages, this probably doesn’t matter much. But if you’re running a content site with paywalled articles, this matters a lot. Gating content behind a 402 means Googlebot can’t read it, which means it won’t rank.

Soft Paywalls vs. Hard Paywalls

The standard approach for SEO-conscious paywall implementations isn’t to return a 402 to everyone. You use something closer to a soft paywall strategy:

• Serve the full content to Googlebot (verified by user-agent or IP range)
• Show registered users the full content after they pay
• Show anonymous users a preview and a paywall prompt

Google has documented that it understands paywalled content and supports structured data (NewsArticle or Article schema with isAccessibleForFree: false) to properly handle it. If you’re just throwing a 402 at everything and hoping Google figures it out, you’re leaving rankings on the table.

Crawl Budget Waste

If a large chunk of your sitemap is returning 402, you’re wasting crawl budget. Google allocates a finite number of crawl requests to your domain. Spending them on 402 URLs instead of crawlable content is a real cost, especially for large sites with thousands of URLs.

The fix is to either noindex payment-gated pages explicitly, exclude them from your sitemap, or implement a soft paywall so Googlebot can access the content even if users can’t. Which option makes sense depends on whether you want those pages to rank at all.

Using Google Search Console to Spot 402s

In Google Search Console, the Coverage report will flag pages returning 4xx errors, including 402s. Check it under Index Coverage. If you start seeing pages move from “Indexed” to “Excluded” with a 4xx reason, cross-reference those URLs against your payment gating implementation. That’s usually the culprit.

Misconceptions About the 402 Status Code

There’s a lot of confused thinking about this status code. Let’s clean some of it up.

“402 means the page doesn’t exist”

No, that’s a 404. A 402 means the resource exists and the server found it. You just can’t access it because payment is involved. Completely different problem with a completely different fix.

“402 and 403 are interchangeable for paywalls”

They’re similar but not the same. A 403 means “forbidden,” implying a permissions problem that might be resolved by logging in with different credentials or being granted access by an admin. A 402 specifically implies money. If you’re building a paywall, 402 is more semantically accurate, though 403 is more commonly used in practice because 402 lacks standardization.

“You should always retry a 402”

Retrying a 402 almost never helps. Unlike a 503 (service unavailable, try again), a 402 is a stable state that requires a human action (paying) to resolve. Automatic retries will just hammer the endpoint and get your client potentially rate-limited.

“The 402 is obsolete and shouldn’t be used”

Nope. It’s still in the current HTTP semantics specification (RFC 9110). It’s used by real APIs in production today. It’s not deprecated. It’s just underspecified, which is different.

“302 and 402 are related because they look similar”

They’re not. A 302 is a redirect, sitting in the 3xx range. A 402 is a client error in the 4xx range. The similar-looking numbers are coincidental. They do completely different things.

Frequently Asked Questions

What does the 402 status code mean?

The 402 status code means “Payment Required.” It’s an HTTP client error response indicating that the request could not be fulfilled because payment is needed. The server found the resource, understood the request, and determined that financial authorization is a prerequisite for access. The exact implementation details aren’t standardized in the HTTP spec, so behavior varies across different platforms and APIs.

Is the 402 status code officially standardized?

Sort of. The 402 status code is defined in RFC 9110, the current HTTP semantics specification, but its behavior is explicitly reserved for future use and left unspecified. There’s no official body format, no required headers, and no defined client behavior. It’s a reserved slot that the web community hasn’t formally standardized, which is why different services implement it differently.

Which APIs actually use the 402 status code?

Stripe uses 402 for card charge failures. Twilio uses it for insufficient account funds. Many SaaS platforms use it for expired trials or exceeded usage limits. GitHub has used it for feature gating in some API contexts. The common thread is: authenticated, valid request, but payment-related access denied.

How should I handle a 402 in my application code?

Don’t retry automatically. Always read the response body, not just the status code. Parse the error body to understand the specific failure reason. Distinguish between user-actionable failures (like a declined card) and admin-actionable failures (like your own API key running out of credits). Surface a clear, human-readable message to the end user and link to where they can resolve the billing issue.

Does a 402 response hurt SEO?

Yes, it can. If Googlebot requests a URL and receives a 402, it cannot access the content and will eventually drop the page from the index after repeated failed crawl attempts. For content you want ranked, either implement a soft paywall that serves content to Googlebot or use structured data to signal paywalled content. Check Google Search Console’s Coverage report to monitor 4xx errors across your site.

What’s the difference between a 402 and a 403 status code?

A 403 means “Forbidden” and signals a permissions problem: you’re not allowed to access this resource, regardless of payment. A 402 specifically signals a payment issue: you would be allowed, but money needs to change hands first. In practice, many developers use 403 for paywalled content because 402 lacks standardization, but 402 is more semantically correct when the barrier is genuinely financial.

Should I use 402 in my API to signal billing issues?

Yeah, it’s a valid choice. If your API gates functionality behind payment and a request fails because of a billing issue, 402 is the most semantically appropriate status code. Pair it with a clear, machine-readable JSON error body that includes an error code, a human-readable message, and ideally a URL pointing to where the user can resolve the billing issue.

What should the response body look like for a 402?

There’s no official standard, but a sensible format includes a status field, an error code string, a human-readable message, and optionally a URL pointing to the billing or payment page. Many APIs also include a more specific internal error code in the body so developers can handle different payment failure scenarios programmatically. Always document your 402 response structure explicitly in your API docs.

Can a 402 status code appear by mistake?

Absolutely. Some older systems and misconfigured servers return 402 when they mean to send a 401 (unauthorized) or 403 (forbidden). If you’re seeing a 402 on a resource that has nothing to do with payments, check the server configuration. It’s likely a bug in the response logic, not an intentional payment gate.

How does 402 differ from 429 (Too Many Requests)?

A 429 means you’ve exceeded a rate limit and need to slow down your requests, usually temporarily. It’s a volume problem. A 402 is a payment problem that won’t resolve by waiting. The 429 response typically includes a Retry-After header telling you when to try again. A 402 requires you to take a financial action before the request will ever succeed.

Does the 402 status code affect crawl budget?

Yes. Any 4xx response from your server, including 402, is a failed crawl request. Google still counts these against your crawl budget. On large sites with thousands of payment-gated URLs, a significant number of 402 responses can mean Google is spending crawl budget on inaccessible pages instead of indexable content. Exclude payment-gated URLs from your sitemap, or implement soft paywall logic to avoid this.

When was the 402 status code first defined?

The 402 status code was first defined in RFC 1945, the HTTP/1.0 specification published in 1996, though it was conceptually included in earlier HTTP discussions from 1992 onward. It was included with the explicit note that it was reserved for future use in anticipation of micropayment systems. Those payment systems never standardized the way early web architects expected, leaving 402 in a perpetual “reserved” state that persists to this day.