The five response classes at a glance
Status codes begin with 1 through 5. Each class tells the client what kind of action, if any, is required next. 1xx responses are provisional and appear during protocol upgrades or long-running operations. 2xx responses mean the request succeeded. 3xx responses instruct the client to take additional steps, often by following a Location header. 4xx responses indicate the client made an error that must be corrected before retrying. 5xx responses mean the server encountered a problem while processing a syntactically valid request.
- 1xx: Informational, request received and processing continues
- 2xx: Successful, request completed as expected
- 3xx: Redirection, further client action required
- 4xx: Client error, request cannot be fulfilled as sent
- 5xx: Server error, server failed to fulfill a valid request
Successful responses and what they confirm
Codes in the 200 range confirm the server accepted and processed the request. 200 OK is the most common and indicates a generic success. 201 Created signals that a new resource was made, usually after a POST. 204 No Content means success with no body returned, common after DELETE operations. These codes tell the client it can proceed without changes to the request. When debugging, a 2xx response rules out network, authentication, and syntax problems, so attention shifts to the payload or application logic.
- 200 OK: Request succeeded with a response body
- 201 Created: New resource created, check Location header
- 204 No Content: Success with no body, often after updates or deletes
Redirection and client error responses
3xx codes require the client to follow a redirect or take another action. 301 Moved Permanently and 302 Found are common when resources change location. In API debugging these often appear when base URLs are outdated. 4xx codes point to client-side mistakes. 400 Bad Request means malformed syntax or invalid parameters. 401 Unauthorized requires valid credentials via the WWW-Authenticate header. 403 Forbidden means the client is authenticated but lacks permission. 404 Not Found indicates the resource does not exist at the requested path. 429 Too Many Requests signals rate limiting and usually includes a Retry-After header.
- Check Location headers on 3xx responses before assuming an error
- 401 requires credentials; 403 requires permission changes
- 429 responses should trigger backoff and respect Retry-After values
Server errors and retry decisions
5xx codes mean the server could not fulfill an otherwise valid request. 500 Internal Server Error is the generic case. 502 Bad Gateway and 503 Service Unavailable often appear during maintenance or upstream failures. 504 Gateway Timeout indicates a timeout waiting for another service. These codes suggest the client should retry later rather than immediately resending the same request. RFC 9110 notes that clients should treat unrecognized codes in a class as equivalent to the generic x00 code, so an unknown 5xx can be handled like 500.
- Retry 5xx responses with exponential backoff and jitter
- Log the full response body for server-side investigation
- Monitor 5xx rates to detect capacity or deployment issues
Practical debugging workflow
Start by capturing the exact request and response, including method, URL, headers, body, and status code. Map the first digit to the class to decide the next step. For 4xx codes, inspect the request for missing fields, wrong content type, or invalid authentication. For 5xx codes, check server logs and recent deployments. For 3xx codes, verify redirect targets and avoid infinite loops. Test with minimal requests first, then add complexity. Use tools that display raw HTTP traffic so status codes are not hidden by client libraries.
- Record request and response in full before changing anything
- Treat 4xx as client fixes and 5xx as server investigation
- Respect rate-limit and retry headers to avoid worsening load