Status Codes and HTTP Headers
Master status-code families and the headers that make APIs interoperable.
Understanding 1xx–5xx Status Codes
HTTP status codes are grouped by their first digit.
1xx: informational2xx: successful processing3xx: redirection or caching-related behavior4xx: client-side request problems5xx: server-side failures
Common API responses include 200 OK, 201 Created, 202 Accepted, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Content, 429 Too Many Requests, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout.
The difference between 401 and 403 is particularly important: 401 indicates missing or invalid authentication credentials, while 403 indicates that the request is understood but the authenticated principal is not permitted to perform the operation.
- Successful creation:
201 Created - Accepted asynchronous work:
202 Accepted - No response body:
204 No Content - Authentication required/invalid:
401 Unauthorized - Permission denied:
403 Forbidden - Resource conflict:
409 Conflict - Rate limited:
429 Too Many Requests
Essential HTTP Headers
Headers are one of the most important parts of a production API. Important request headers include Accept, Content-Type, Authorization, If-Match, If-None-Match, If-Modified-Since, Idempotency-Key, Origin, and tracing headers such as traceparent.
Important response headers include Content-Type, Location, Cache-Control, ETag, Last-Modified, Retry-After, WWW-Authenticate, Allow, Access-Control-Allow-Origin, and rate-limit metadata.
Headers should not be treated as arbitrary strings. Many have defined HTTP semantics that clients, proxies, browsers, and caches understand automatically.
application/jsonapplication/jsonBearer TOKEN/users/42"user-42-v7"Content Negotiation and Media Types
Clients and servers can negotiate representation formats using headers such as Accept and Content-Type.
A client might send Accept: application/json, indicating that it wants JSON. A request containing JSON normally sends Content-Type: application/json.
Media types can also be vendor-specific or versioned, for example application/vnd.example.user+json. Content negotiation is different from URI versioning because the representation format is negotiated through HTTP metadata rather than encoded in the path.
A robust API validates unsupported media types and can respond with 415 Unsupported Media Type when the request body format is not supported.
Acceptdescribes preferred response representations.Content-Typedescribes the body being sent or returned.- Media types can be used for sophisticated representation negotiation.