402

Payment Required

4xx Client Error

Back to list

Server perspective

Treat 402 as a nonstandard, reserved status that some products use for billing or subscription gates.

When to use

  • Use 402 only when your API contract explicitly documents that convention
  • Prefer more established product contracts when broad interoperability matters

How to respond

  • Explain the billing condition clearly in the response body
  • Document whether the client should upgrade a plan, add funds, or resolve an invoice

Headers to consider

  • No status-specific header is required; still send normal HTTP metadata such as Content-Type, caching, or tracing headers when they help the client.

Response body

  • Include product-specific billing details because 402 does not have a universal standard workflow

Server-side pitfalls

  • Do not assume generic clients or browsers attach special meaning to 402
  • Do not use 402 as if it were a widely interoperable standards-based replacement for 403

Examples

Payment step required by product contract

Request:POST /api/subscription/activate without a valid payment method
Response:402 Payment Required with error: payment_method_required

The API uses 402 only because its contract defines a payment recovery flow.

References

Related 4xx Client Error Codes

400

Bad Request

Your request doesn't make sense or has mistakes in it. Check what you're sending and try again.

401

Unauthorized

You need to prove who you are before you can access this. Please log in or provide valid credentials.

403

Forbidden

I know who you are, but you're not allowed to do this. You don't have permission for this action.

404

Not Found

The thing you're looking for doesn't exist here. It's like knocking on a door and nobody's home.

405

Method Not Allowed

You found the right place, but you're trying to do something that's not allowed here. Try a different action.

406

Not Acceptable

I can't give you the data in the format you want. I have the data, but not in XML/JSON/etc. that you asked for.

407

Proxy Authentication Required

You need to authenticate with the proxy server first before it will forward your request to the destination.

408

Request Timeout

You took too long to send your request. The server got tired of waiting and gave up.

409

Conflict

There's a conflict - what you're trying to do clashes with something that already exists or the current state.

410

Gone

This used to exist here, but it's been permanently removed and won't be coming back.

411

Length Required

You're trying to send me something, but you didn't tell me how big it is. I need to know the size before I can accept it.

412

Precondition Failed

You said 'only do this if that thing is true', but that thing turned out to be false, so I didn't do anything.

413

Content Too Large

The file or data you're trying to send is too big for me to handle. Please make it smaller.

414

URI Too Long

The web address (URL) you're using is too long for me to handle. Please make it shorter or use a different method.

415

Unsupported Media Type

I don't understand the format of data you sent me. Please send it as JSON, XML, or another format I support.

416

Range Not Satisfiable

You asked for a specific part of a file (like pages 50-60), but the file only has 10 pages. I can't give you what doesn't exist.

417

Expectation Failed

You told me to expect something specific to happen, but I can't make that happen the way you want.

418

I'm a teapot

I'm a teapot, not a coffee maker! This is an April Fools' joke code - don't use it in real APIs.

421

Misdirected Request

You sent your request to the wrong server. It's like calling the wrong phone number - the person who answered can't help you.

422

Unprocessable Content

Your request looks right, but the data doesn't make sense according to our business rules. Fix the data and try again.

WebDAV
423

Locked

This file is currently being edited by someone else and they've locked it. You'll have to wait until they're done or unlock it.

WebDAV
424

Failed Dependency

I couldn't do what you asked because something else you wanted me to do first didn't work out. It's like a domino effect - one failure caused this one.

WebDAV
425

Too Early

You're trying to do something too early in the connection process. It's like trying to order food before the restaurant is fully open.

426

Upgrade Required

You need to upgrade to a newer or different protocol to access this. It's like needing to update your app to continue using it.

428

Precondition Required

You're trying to change something, but you need to tell me what you expect it to look like first, so we don't accidentally overwrite someone else's changes.

429

Too Many Requests

Slow down! You're making too many requests too quickly. Wait a bit and try again later.

431

Request Header Fields Too Large

Your request headers (the extra information like cookies) are too big for me to handle. Clean up your cookies or make the headers smaller.

451

Unavailable For Legal Reasons

This content is blocked by law or legal restrictions in your area. It's like a book that's banned in your country.