We use cookies to understand how the site is used and to display ads. Analytics and advertising only run after you accept. You can change your choice anytime. Privacy policy

Skip to content
devvkit
$devvkit resources --cheatsheet http-status-codes-cheatsheet

HTTP Status Codes Cheatsheet

[api]

Every HTTP status code explained: from 100s to 500s, with what each code means and exactly when to use it.61 commands · 5 sections

HTTP status codes tell clients whether a request succeeded, failed, or needs action. This cheatsheet covers every code class: informational 1xx, success 2xx, redirection 3xx, client errors 4xx, and server errors 5xx.

Each entry shows the code, its meaning, and the use case: when your API should return it and what clients should do with it.

1xx Informational4

$100 Continue
Use case: Server received headers, client may send the body: large uploads.Example: Expect: 100-continue header
$101 Switching Protocols
Use case: Upgrade to WebSocket or HTTP/2: connection protocol change.Example: WebSocket handshake response
$102 Processing
Use case: Server is still working: long operations (WebDAV).Example: server sends 102 then final response
$103 Early Hints
Use case: Send <link rel="preload"> headers before the final response: faster page loads.Example: preload CSS/JS while the server renders

2xx Success9

$200 OK
Use case: Request succeeded: the default success for GET, PUT, PATCH.Example: GET /users → 200 with the list
$201 Created
Use case: A resource was created: return with Location header.Example: POST /users → 201 + Location: /users/42
$202 Accepted
Use case: Accepted for async processing: job queues, webhooks.Example: POST /jobs → 202, job runs later
$204 No Content
Use case: Success with an empty body: deletions and silent updates.Example: DELETE /users/42 → 204
$205 Reset Content
Use case: Tell the client to reset the document view: form resets.Example: POST /forms/submit → 205
$206 Partial Content
Use case: Partial response: range requests, video streaming, resumable downloads.Example: GET /video.mp4 with Range header → 206
$207 Multi-Status
Use case: Mixed statuses in one body: batch operations (WebDAV).Example: batch update → 207 with per-item statuses
$208 Already Reported
Use case: Resource already listed earlier in a DAV response.Example: WebDAV PROPFIND depth-2
$226 IM Used
Use case: Server applied instance manipulation (delta encoding).Example: rare, RFC 3229

3xx Redirection7

$300 Multiple Choices
Use case: Multiple representations available: rarely used; pick one and redirect.Example: content negotiation variants
$301 Moved Permanently
Use case: Permanent redirect: update bookmarks, link equity passes, method may change to GET.Example: http:// → https://, domain migration
$302 Found
Use case: Temporary redirect: browser keeps the original URL and method.Example: logged-out → login page
$303 See Other
Use case: Redirect to GET after a POST: PRG (Post/Redirect/Get) pattern.Example: form submit → 303 → success page
$304 Not Modified
Use case: Cache is still valid: respond with ETag/Last-Modified checks.Example: GET with If-None-Match → 304, empty body
$307 Temporary Redirect
Use case: Temporary redirect KEEPING the method and body: unlike 302.Example: POST → 307 → POST again elsewhere
$308 Permanent Redirect
Use case: Permanent redirect KEEPING method and body: POST stays POST.Example: API endpoint moved, re-post to new URL

4xx Client Errors29

$400 Bad Request
Use case: Malformed request: bad JSON, invalid syntax. The client must fix it.Example: {"name": "x", } → 400
$401 Unauthorized
Use case: Not authenticated: missing or invalid credentials. Retry WITH auth.Example: GET /me without token → 401 + WWW-Authenticate
$402 Payment Required
Use case: Reserved for digital payments: rarely used.Example: paywalled API endpoints
$403 Forbidden
Use case: Authenticated but NOT allowed: no access to this resource.Example: free-tier user hits a pro endpoint → 403
$404 Not Found
Use case: Resource does not exist: or is hidden for security.Example: GET /users/999 → 404
$405 Method Not Allowed
Use case: Wrong method for this route: return Allow header.Example: DELETE on a GET-only route → 405 + Allow: GET
$406 Not Acceptable
Use case: Cannot produce the requested Accept format.Example: Accept: application/xml but only JSON → 406
$407 Proxy Authentication Required
Use case: Must authenticate with the proxy first.Example: corporate proxies
$408 Request Timeout
Use case: Client took too long to send the request: server gave up.Example: idle keep-alive connections
$409 Conflict
Use case: Request conflicts with the current state: version conflicts, duplicate create.Example: POST /users with an existing email → 409
$410 Gone
Use case: Resource existed but was removed permanently: no retry.Example: retired API endpoints
$411 Length Required
Use case: Content-Length header missing where required.Example: chunked uploads without length
$412 Precondition Failed
Use case: Conditional headers (If-Match, If-None-Match) failed: optimistic locking.Example: PATCH with stale ETag → 412
$413 Payload Too Large
Use case: Request body exceeds the server limit.Example: uploading a 2GB file to a 100MB cap
$414 URI Too Long
Use case: URL too long: often GET requests with huge query strings.Example: GET with a giant filter parameter
$415 Unsupported Media Type
Use case: Content-Type is not supported by the endpoint.Example: sending XML to a JSON-only API
$416 Range Not Satisfiable
Use case: Range header does not match the resource: return Content-Range.Example: Range: bytes=999999- on a small file
$417 Expectation Failed
Use case: The Expect header's expectation cannot be met.Example: Expect: 100-continue on unsupported server
$418 I'm a teapot
Use case: A joke from RFC 2324: occasionally used as an easter egg.Example: HTCPCP teapots
$421 Misdirected Request
Use case: Request sent to a server that cannot respond: shared hosting, SNI issues.Example: HTTP/2 server with wrong host
$422 Unprocessable Entity
Use case: Request is valid JSON but semantically invalid: validation errors.Example: POST /users with missing required field → 422
$423 Locked
Use case: Resource is locked (WebDAV).Example: editing a checked-out document
$424 Failed Dependency
Use case: Request depends on another request that failed (WebDAV).Example: batch operations
$425 Too Early
Use case: Server refuses the request: potential replay attack risk.Example: early TLS 1.3 data
$426 Upgrade Required
Use case: Client must switch protocols: upgrade to HTTP/2 or TLS.Example: Upgrade: TLS/1.0 required
$428 Precondition Required
Use case: Server requires If-Match/If-None-Match: prevents lost updates.Example: concurrent edit protection
$429 Too Many Requests
Use case: Rate limited: include Retry-After header. THE rate-limit code.Example: API rate limit exceeded → 429 + Retry-After: 60
$431 Request Header Fields Too Large
Use case: Headers exceed the server limit: cookie or auth bloat.Example: huge cookie jar or oversized Authorization
$451 Unavailable For Legal Reasons
Use case: Blocked by legal requirements: censorship and takedowns.Example: content removed by court order

5xx Server Errors12

$500 Internal Server Error
Use case: Unexpected server failure: do NOT leak details in the body.Example: unhandled exception → 500 + generic message
$501 Not Implemented
Use case: Server does not support the requested feature: method not implemented.Example: custom method on a plain server
$502 Bad Gateway
Use case: Upstream server returned an invalid response: nginx behind a broken app.Example: reverse proxy → dead upstream → 502
$503 Service Unavailable
Use case: Server is overloaded or down for maintenance: include Retry-After.Example: deploys, capacity spikes
$504 Gateway Timeout
Use case: Upstream took too long: proxy timed out waiting.Example: slow database behind the API gateway
$505 HTTP Version Not Supported
Use case: The HTTP version in the request is not supported.Example: HTTP/0.9 relic
$506 Variant Also Negotiates
Use case: Transparent content negotiation misconfigured (rare).Example: negotiation loops
$507 Insufficient Storage
Use case: Server cannot store the representation: disk full (WebDAV).Example: quota exceeded on the server
$508 Loop Detected
Use case: Infinite processing loop detected (WebDAV).Example: circular DAV references
$510 Not Extended
Use case: Further extensions required to fulfill the request (rare).Example: RFC 2774 extensions
$511 Network Authentication Required
Use case: Client must authenticate to the NETWORK: captive portals.Example: Wi-Fi login pages
$520-527 (Cloudflare-specific)
Use case: Cloudflare-specific errors: 520 unknown, 521 down, 522 timeout, 523 unreachable, 524 timeout, 525 SSL, 526 invalid SSL, 527 Railgun.Example: 521 = origin server is offline

Frequently asked questions

What does a 404 status code mean?

404 Not Found means the server cannot find the requested resource. Unlike 410 Gone, the resource may exist again later, so 404 is the correct response for unknown or removed URLs you do not want to signal permanently.

What is the difference between 301 and 302 redirects?

301 Moved Permanently tells clients and search engines the URL has permanently changed: bookmarks and link equity are updated. 302 Found is a temporary redirect used for short-lived moves; browsers keep the original URL.

When should I return 429?

Return 429 Too Many Requests when a client exceeds your rate limit. Include a Retry-After header so clients know when to try again, and use the response to trigger backoff logic on the client.

What is the difference between 401 and 403?

401 Unauthorized means the request lacks valid authentication: send credentials and retry. 403 Forbidden means authentication succeeded but the user lacks permission for that resource. 401 is about identity, 403 about access.