DEV Community

楊東霖
楊東霖

Posted on • Originally published at devplaybook.cc

Complete HTTP Status Codes Reference for REST API Devs

#webdev #programming #rest #api

HTTP status codes are the contract language of APIs. When your frontend receives a response, the status code is the first signal: did it work, where did it go, what went wrong? A good API uses status codes precisely; a confusing API returns 200 OK with "error": true in the body.

This reference covers every status code you'll encounter in REST API development—with the context, examples, and gotchas that actually matter. Use the DevPlaybook HTTP Status Codes Tool to look up any code quickly.

Status Code Categories

Range Category Your API Should...
1xx Informational Rarely return these manually
2xx Success Be specific: 200 vs 201 vs 204
3xx Redirection Use 301/308 for permanent, 302/307 for temporary
4xx Client Error Be descriptive: explain what the client did wrong
5xx Server Error Never expose internals; log details server-side

1xx — Informational

Informational codes are protocol-level responses that indicate the server received the request and is processing it. REST APIs rarely return these explicitly—they're typically handled at the HTTP/infrastructure layer.

100 Continue

The server received the request headers and the client should proceed with the request body. Used when clients send an Expect: 100-continue header before sending large payloads.

Practical note: Most HTTP clients handle this automatically. You'll encounter it when uploading large files or request bodies.

101 Switching Protocols

The server accepts the client's request to switch protocols—most commonly HTTP → WebSocket.

// Client initiates WebSocket upgrade
const ws = new WebSocket('wss://api.example.com/ws');
// Server responds with 101 Switching Protocols
// Upgrade: websocket
// Connection: Upgrade
Enter fullscreen mode Exit fullscreen mode

103 Early Hints

Allows the server to send response headers before the final HTTP message, enabling the client to start preloading resources. Used in CDN/edge optimization, not typically in API responses.

2xx — Success

200 OK

The default success response. The request succeeded and the response body contains the result.

Use for:

  • GET requests that return data
  • POST requests that return the created/updated resource
  • PUT/PATCH requests when returning the updated resource 
GET /api/users/42
→ 200 OK
{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Don't use 200 when:

  • Nothing was returned (use 204)
  • A resource was created (use 201)
  • The request is being processed asynchronously (use 202)

201 Created

A new resource was created successfully. Should include a Location header pointing to the new resource.

POST /api/users
{ "name": "Bob", "email": "bob@example.com" }
→ 201 Created
Location: /api/users/43
{
  "id": 43,
  "name": "Bob",
  "email": "bob@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Always return the created resource (or at minimum the ID) in the body. Forcing clients to make a separate GET request is unnecessary friction.

202 Accepted

The request was accepted for processing, but processing is not yet complete. The classic async operation response.

POST /api/reports/generate
{ "type": "monthly", "month": "2026-02" }
→ 202 Accepted
{
  "jobId": "job_abc123",
  "statusUrl": "/api/jobs/job_abc123",
  "estimatedSeconds": 30
}
Enter fullscreen mode Exit fullscreen mode

Always include a way to check status—either a statusUrl in the body or a polling endpoint.

204 No Content

The request succeeded, but there's no content to return. The browser/client should not navigate away from the current page.

Use for:

  • DELETE operations (resource successfully deleted)
  • PUT/PATCH when you don't want to return the full resource
  • Any successful operation with no meaningful response body 
DELETE /api/users/42
→ 204 No Content
(empty body)
Enter fullscreen mode Exit fullscreen mode

Common mistake: Returning 200 with an empty body. Use 204 instead—it explicitly signals "success, nothing to show."

206 Partial Content

The server is delivering part of the resource due to a range request. Used for large file downloads, video streaming, and chunked data transfer.

GET /api/files/video.mp4
Range: bytes=0-1048575
→ 206 Partial Content
Content-Range: bytes 0-1048575/52428800
Content-Type: video/mp4
Enter fullscreen mode Exit fullscreen mode

3xx — Redirection

301 Moved Permanently

The resource has permanently moved to a new URL. Browsers and HTTP clients should cache this redirect and update their bookmarks/links.

GET /api/v1/users
→ 301 Moved Permanently
Location: /api/v2/users
Enter fullscreen mode Exit fullscreen mode

Important: 301 redirects cause POST requests to become GET requests in many clients (legacy behavior). Use 308 for permanent redirects that preserve the HTTP method.

302 Found (Temporary Redirect)

The resource is temporarily at a different URL. Clients should continue to use the original URL for future requests. Same method-change caveat as 301—use 307 to preserve the method.

304 Not Modified

The resource hasn't changed since the client's last request. Used with conditional requests (If-Modified-Since, If-None-Match).

GET /api/articles/10
If-None-Match: "abc123"
→ 304 Not Modified
(empty body — client uses cached version)
Enter fullscreen mode Exit fullscreen mode

Implementing 304 properly can dramatically reduce bandwidth for read-heavy APIs.

307 Temporary Redirect

Same as 302 but explicitly preserves the HTTP method. A POST request to a 307 location stays a POST.

308 Permanent Redirect

Same as 301 but preserves the HTTP method. The correct choice when permanently redirecting non-GET endpoints.

4xx — Client Errors

The 4xx range is where REST API design matters most. Vague error responses make debugging painful; precise error responses make integrators productive.

400 Bad Request

The request is malformed or contains invalid data.

// Request
POST /api/users
{ "email": "not-an-email", "age": -5 }

// Response: 400 Bad Request
{
  "error": "validation_failed",
  "message": "Request contains invalid fields",
  "details": [
    { "field": "email", "code": "invalid_format", "message": "Must be a valid email address" },
    { "field": "age", "code": "out_of_range", "message": "Must be a positive number" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Best practice: Return all validation errors at once, not just the first one. Include field names and human-readable messages.

401 Unauthorized

Authentication is required and has not been provided, or the provided credentials are invalid.

GET /api/profile
(no Authorization header)
→ 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
{
  "error": "authentication_required",
  "message": "Please provide a valid Bearer token"
}
Enter fullscreen mode Exit fullscreen mode

Common confusion: 401 means "not authenticated." 403 means "authenticated but not authorized." The naming is historical and confusing—just remember: 401 = who are you? 403 = I know who you are, but no.

403 Forbidden

The client is authenticated but lacks permission to access the requested resource.

// 403 Forbidden
{
  "error": "insufficient_permissions",
  "message": "You do not have access to this resource",
  "required_role": "admin"
}
Enter fullscreen mode Exit fullscreen mode

Privacy consideration: For sensitive resources, returning 404 instead of 403 prevents enumeration attacks—the client can't tell if the resource exists or is just restricted. Choose based on your security model.

404 Not Found

The requested resource does not exist.

// 404 Not Found
{
  "error": "not_found",
  "message": "User with ID 99999 not found"
}
Enter fullscreen mode Exit fullscreen mode

Use consistently for:

  • Resource IDs that don't exist
  • Routes that don't exist (handled by your router automatically)
  • Resources deleted in the past (return 410 Gone if you want to distinguish)

405 Method Not Allowed

The HTTP method used is not supported for this endpoint. Must include an Allow header listing valid methods.

DELETE /api/articles/10/comments
→ 405 Method Not Allowed
Allow: GET, POST
Enter fullscreen mode Exit fullscreen mode

408 Request Timeout

The client took too long to send the request. The server closed the connection. Rare in REST APIs but possible with slow upload connections.

409 Conflict

The request conflicts with the current state of the resource. Common for:

  • Duplicate creation attempts
  • Optimistic concurrency conflicts
  • State machine violations 
// 409 Conflict — duplicate email
{
  "error": "conflict",
  "message": "A user with this email already exists",
  "field": "email"
}

// 409 Conflict — optimistic lock
{
  "error": "conflict",
  "message": "Resource was modified since you last fetched it",
  "current_version": 7,
  "your_version": 5
}
Enter fullscreen mode Exit fullscreen mode

410 Gone

The resource existed but has been permanently deleted. Unlike 404, 410 signals to search engines and caches that the URL should be removed.

// 410 Gone
{
  "error": "resource_deleted",
  "message": "This account was permanently deleted on 2025-01-15"
}
Enter fullscreen mode Exit fullscreen mode

413 Content Too Large

The request body exceeds the server's configured limit.

// 413 Content Too Large
{
  "error": "payload_too_large",
  "message": "Request body exceeds 10MB limit",
  "max_bytes": 10485760
}
Enter fullscreen mode Exit fullscreen mode

415 Unsupported Media Type

The request's Content-Type is not supported by this endpoint.

// 415 Unsupported Media Type
{
  "error": "unsupported_media_type",
  "message": "Content-Type must be application/json",
  "supported": ["application/json", "application/x-www-form-urlencoded"]
}
Enter fullscreen mode Exit fullscreen mode

422 Unprocessable Entity

The request is syntactically correct but semantically invalid—the data can be parsed but violates business rules.

// Request: valid JSON, but business rule violated
POST /api/invoices
{ "amount": 100, "currency": "XYZ" }

// 422 Unprocessable Entity
{
  "error": "unprocessable",
  "message": "Currency XYZ is not supported",
  "supported_currencies": ["USD", "EUR", "GBP"]
}
Enter fullscreen mode Exit fullscreen mode

400 vs 422: Use 400 for structural problems (malformed JSON, missing required fields). Use 422 for semantic problems (valid request that violates business logic).

429 Too Many Requests

The client has exceeded the rate limit. Must include Retry-After and ideally rate limit headers.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711060000

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please wait 60 seconds.",
  "retry_after": 60
}
Enter fullscreen mode Exit fullscreen mode

451 Unavailable For Legal Reasons

The resource is not available due to legal demands (censorship, court orders, DMCA). Named after Fahrenheit 451.

5xx — Server Errors

5xx errors indicate the server failed to fulfill a valid request. Rule #1: never expose internal error details (stack traces, database errors, file paths) in 5xx responses. Log everything, return minimal information.

500 Internal Server Error

The default server error. Something unexpected happened.

// What you return to the client
{
  "error": "internal_server_error",
  "message": "An unexpected error occurred",
  "request_id": "req_abc123"
}

// What you log on the server (never send to client)
{
  "timestamp": "2026-03-21T10:30:00Z",
  "request_id": "req_abc123",
  "error": "TypeError: Cannot read properties of undefined (reading 'userId')",
  "stack": "...",
  "user_id": 42,
  "route": "GET /api/profile"
}
Enter fullscreen mode Exit fullscreen mode

Include a request_id in error responses so support teams can correlate client reports to server logs.

501 Not Implemented

The server does not support the functionality required to fulfill the request. Returned for HTTP methods the server doesn't implement at all (rare in practice).

502 Bad Gateway

A proxy/gateway server received an invalid response from an upstream server. Common in microservices: your API gateway can't reach a downstream service.

503 Service Unavailable

The server is temporarily unable to handle requests—due to maintenance, overload, or dependency failure. Include Retry-After when possible.

HTTP/1.1 503 Service Unavailable
Retry-After: 120

{
  "error": "service_unavailable",
  "message": "The service is temporarily unavailable for scheduled maintenance",
  "retry_after": 120,
  "status_url": "https://status.example.com"
}
Enter fullscreen mode Exit fullscreen mode

504 Gateway Timeout

A proxy/gateway server didn't receive a timely response from an upstream server. Common in API integrations and microservice chains with slow dependencies.

REST API Error Response Best Practices

Consistent Error Shape

Pick a structure and stick to it across all error responses:

interface ApiError {
  error: string;       // Machine-readable error code: "not_found", "validation_failed"
  message: string;     // Human-readable description
  request_id: string;  // For support correlation
  details?: Array<{    // Optional: field-level errors
    field: string;
    code: string;
    message: string;
  }>;
  docs_url?: string;   // Link to relevant API documentation
}
Enter fullscreen mode Exit fullscreen mode

Never Return 200 with Error in Body 

// Bad — forces clients to parse body to detect errors
200 OK
{ "success": false, "error": "User not found" }

// Good — HTTP status code carries the error signal
404 Not Found
{ "error": "not_found", "message": "User not found" }
Enter fullscreen mode Exit fullscreen mode

Use Status Codes for Caching

  • 200 responses are cacheable by default (with proper Cache-Control)
  • 404 and 410 can be cached (CDN can serve cached 404s)
  • 401 and 403 should not be cached
  • 500 should not be cached

Return Helpful 4xx Messages 

// Unhelpful
{ "error": "Bad Request" }

// Helpful
{
  "error": "validation_failed",
  "message": "The request body is missing required fields",
  "details": [
    { "field": "email", "code": "required", "message": "Email address is required" }
  ],
  "docs_url": "https://api.example.com/docs/users#create"
}
Enter fullscreen mode Exit fullscreen mode

Quick Reference Table

Code Name When to Use
200 OK Standard success with response body
201 Created Resource created (POST)
202 Accepted Async operation queued
204 No Content Success, no response body (DELETE)
206 Partial Content Range request fulfilled
301 Moved Permanently Permanent redirect (changes to GET)
304 Not Modified Conditional GET — use cached version
307 Temporary Redirect Temp redirect, preserve method
308 Permanent Redirect Permanent redirect, preserve method
400 Bad Request Malformed request or validation error
401 Unauthorized Not authenticated
403 Forbidden Authenticated but not authorized
404 Not Found Resource doesn't exist
405 Method Not Allowed HTTP method not supported
409 Conflict State conflict or duplicate
410 Gone Resource permanently deleted
413 Content Too Large Request body too big
415 Unsupported Media Type Wrong Content-Type
422 Unprocessable Entity Semantic validation failure
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Unexpected server failure
502 Bad Gateway Upstream server error
503 Service Unavailable Server overloaded or in maintenance
504 Gateway Timeout Upstream server timeout

Explore More

The DevPlaybook HTTP Status Codes Tool provides a searchable reference for every HTTP status code with descriptions and use cases. Keep it open when designing your API contract or debugging integration issues.

For testing your API's status code responses, the API Request Builder lets you send requests and inspect responses directly in the browser.

Need to test regex patterns on API response bodies? The Regex Tester makes it easy. Working with JWT authentication in your API? Check out our JWT Decoder guide.

Level Up Your Dev Workflow

Found this useful? Explore DevPlaybook — cheat sheets, tool comparisons, and hands-on guides for modern developers.

🛒 Get the DevToolkit Starter Kit on Gumroad — 40+ browser-based dev tools, source code + deployment guide included.

Top comments (0)