$devvkit resources --cheatsheet http-status-codes-cheatsheet

HTTP Status Codes Cheatsheet

[api]

Every HTTP status code you need to know for building and debugging REST APIs.

HTTP status codes are three-digit responses from the server indicating the result of a request. They are grouped into five classes: 1xx (informational), 2xx (success), 3xx (redirection), 4xx (client error), and 5xx (server error).

This cheatsheet covers the most common codes. Use 200 for successful reads, 201 for resource creation, 204 for deletions, 4xx for client mistakes, and 5xx for server failures.

2xx Success

$200 OK

Standard success response. The request has succeeded.Example: GET /api/users returns a list of users

$201 Created

A new resource was successfully created.Example: POST /api/users returns the new user with a Location header

$202 Accepted

Request accepted but processing is not yet complete. Used for async operations.Example: POST /api/jobs starts a background task

$204 No Content

Request succeeded but there is no response body.Example: DELETE /api/users/1 returns nothing on success

3xx Redirection

$301 Moved Permanently

Resource has been permanently moved to a new URL. Clients should update bookmarks.Example: API v1 endpoint migrated to /api/v2/

$302 Found

Resource temporarily available at a different URL. Use the Location header for the redirect.Example: Login redirect after successful authentication

$304 Not Modified

Cached version is still valid. Used with conditional GET (If-None-Match, If-Modified-Since).Example: Browser cached resource is still fresh

4xx Client Errors

$400 Bad Request

Server cannot process the request due to malformed syntax or invalid data.Example: Request body contains invalid JSON or missing required fields

$401 Unauthorized

Authentication is required and has failed or was not provided.Example: API key is missing or invalid in the Authorization header

$403 Forbidden

Client is authenticated but does not have permission to access the resource.Example: User role does not have admin privileges

$404 Not Found

The requested resource does not exist on the server.Example: GET /api/users/999 where user 999 does not exist

$405 Method Not Allowed

The HTTP method is not supported for this endpoint.Example: DELETE on a read-only endpoint

$409 Conflict

Request conflicts with the current state of the resource.Example: Trying to create a user with an email that already exists

$410 Gone

Resource is intentionally disabled and will not be available again. No forwarding address.Example: Deprecated API endpoint that was removed

$422 Unprocessable Content

Request body is syntactically correct but semantically invalid (validation failed).Example: Email field does not pass format validation

$429 Too Many Requests

Client has exceeded the rate limit. Check Retry-After header.Example: More than 100 requests per minute to the API

5xx Server Errors

$500 Internal Server Error

Generic server error. The server encountered an unexpected condition.Example: Unhandled exception in the application code

$502 Bad Gateway

Server acting as a gateway received an invalid response from an upstream server.Example: Nginx receives a malformed response from the Node.js backend

$503 Service Unavailable

Server is temporarily unable to handle the request (overloaded or under maintenance).Example: Server is down for a scheduled database migration

$504 Gateway Timeout

Upstream server failed to respond in time. Common with proxied databases or microservices.Example: PostgreSQL query takes longer than the load balancer timeout

HTTP Status Codes Cheatsheet

Every HTTP status code you need to know for building and debugging REST APIs.

This cheatsheet covers the most common codes. Use 200 for successful reads, 201 for resource creation, 204 for deletions, 4xx for client mistakes, and 5xx for server failures.

2xx Success

200 OK — Standard success response. The request has succeeded.

Example: GET /api/users returns a list of users

201 Created — A new resource was successfully created.

Example: POST /api/users returns the new user with a Location header

202 Accepted — Request accepted but processing is not yet complete. Used for async operations.

Example: POST /api/jobs starts a background task

204 No Content — Request succeeded but there is no response body.

Example: DELETE /api/users/1 returns nothing on success

3xx Redirection

301 Moved Permanently — Resource has been permanently moved to a new URL. Clients should update bookmarks.

Example: API v1 endpoint migrated to /api/v2/

302 Found — Resource temporarily available at a different URL. Use the Location header for the redirect.

Example: Login redirect after successful authentication

304 Not Modified — Cached version is still valid. Used with conditional GET (If-None-Match, If-Modified-Since).

Example: Browser cached resource is still fresh

4xx Client Errors

400 Bad Request — Server cannot process the request due to malformed syntax or invalid data.

Example: Request body contains invalid JSON or missing required fields

401 Unauthorized — Authentication is required and has failed or was not provided.

Example: API key is missing or invalid in the Authorization header

403 Forbidden — Client is authenticated but does not have permission to access the resource.

Example: User role does not have admin privileges

404 Not Found — The requested resource does not exist on the server.

Example: GET /api/users/999 where user 999 does not exist

405 Method Not Allowed — The HTTP method is not supported for this endpoint.

Example: DELETE on a read-only endpoint

409 Conflict — Request conflicts with the current state of the resource.

Example: Trying to create a user with an email that already exists

410 Gone — Resource is intentionally disabled and will not be available again. No forwarding address.

Example: Deprecated API endpoint that was removed

422 Unprocessable Content — Request body is syntactically correct but semantically invalid (validation failed).

Example: Email field does not pass format validation

429 Too Many Requests — Client has exceeded the rate limit. Check Retry-After header.

Example: More than 100 requests per minute to the API

5xx Server Errors

500 Internal Server Error — Generic server error. The server encountered an unexpected condition.

Example: Unhandled exception in the application code

502 Bad Gateway — Server acting as a gateway received an invalid response from an upstream server.

Example: Nginx receives a malformed response from the Node.js backend

503 Service Unavailable — Server is temporarily unable to handle the request (overloaded or under maintenance).

Example: Server is down for a scheduled database migration

504 Gateway Timeout — Upstream server failed to respond in time. Common with proxied databases or microservices.

Example: PostgreSQL query takes longer than the load balancer timeout