HTTP Status Code Reference

Continue

The server has received the request headers, and the client should proceed to send the request body.

Use when: Used in Expect: 100-continue header flow.

Switching Protocols

The server is switching protocols as requested by the client.

Use when: Used when upgrading to WebSocket (Upgrade: websocket header).

OK

The request succeeded. The response body contains the requested resource.

Use when: Standard success response for GET, PUT, PATCH requests.

Created

The request succeeded and a new resource was created.

Use when: Use for successful POST requests that create a resource. Include Location header.

Accepted

The request has been accepted for processing, but processing is not complete.

Use when: Use for async operations — job queued but not yet finished.

No Content

The server successfully processed the request and is not returning any content.

Use when: Use for successful DELETE requests and PUT/PATCH with no response body.

Partial Content

The server is delivering only part of the resource due to a Range header.

Use when: Used in video streaming and resumable file downloads.

Moved Permanently

The resource has been permanently moved to a new URL.

Use when: Use for permanent URL changes. Browsers and search engines update their links.

Found (Temporary Redirect)

The resource is temporarily at a different URL.

Use when: Use for temporary redirects. Do NOT use for permanent moves (use 301).

Not Modified

The cached version of the resource is still valid.

Use when: Returned when If-None-Match/If-Modified-Since headers match. Saves bandwidth.

Temporary Redirect

Same as 302 but explicitly preserves the HTTP method.

Use when: Use instead of 302 when you need to keep POST method on redirect.

Permanent Redirect

Same as 301 but explicitly preserves the HTTP method.

Use when: Use instead of 301 when you need to keep POST method on permanent redirect.

Bad Request

The server cannot process the request due to malformed syntax.

Use when: Malformed JSON, missing required fields, invalid parameter types.

Unauthorized

Authentication is required and has failed or not been provided.

Use when: No token, expired token, or invalid credentials. Return WWW-Authenticate header.

Forbidden

The server understood the request but refuses to authorize it.

Use when: Authenticated but lacks permission. Unlike 401, re-authenticating won't help.

Not Found

The requested resource could not be found.

Use when: Resource doesn't exist. Also used to hide 403s for security (don't reveal existence).

Method Not Allowed

The HTTP method is not allowed for this resource.

Use when: GET-only endpoint received a POST. Include Allow header with valid methods.

Request Timeout

The server timed out waiting for the request.

Use when: Client took too long to send the full request. Server may close connection.

Conflict

The request conflicts with the current state of the resource.

Use when: Duplicate username, version conflict in optimistic locking, resource state mismatch.

Gone

The resource is no longer available and will not return.

Use when: Permanently deleted resources. More definitive than 404.

Unprocessable Entity

The request is well-formed but cannot be processed due to semantic errors.

Use when: Validation errors (email format wrong, value out of range). Common in REST APIs.

Too Many Requests

The user has sent too many requests in a given time period.

Use when: Rate limiting. Include Retry-After header to tell client when to retry.

Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request.

Use when: Unhandled exceptions, database errors. Log the error but don't expose details to client.

Not Implemented

The server does not support the functionality required to fulfill the request.

Use when: HTTP method not implemented. Different from 405 (method exists but not for this resource).

Bad Gateway

The server, acting as a gateway, received an invalid response from an upstream server.

Use when: Nginx/proxy can't reach your app server. Common during deployments.

Service Unavailable

The server is currently unavailable (overloaded or down for maintenance).

Use when: Planned downtime or overload. Include Retry-After header.

Gateway Timeout

The server, acting as a gateway, did not receive a timely response from an upstream server.

Use when: Upstream service is too slow. Common with slow database queries or external API calls.