# HTTP status codes A selected guide to response classes, common codes, redirects, retries, and the headers that change what a client should do. Waypoint Reference · Version 2026.10.3 All network records are synthetic examples. ## Start with the class HTTP status codes are protocol standards; the relay fixtures elsewhere on this site are synthetic. Each status code has three digits. The first digit gives the broad result; the remaining digits identify a more specific condition. A 1xx response is interim and can be followed by a final response. The other classes describe the final response. This is a selected working guide, not the complete set of assigned codes. Use the IANA registry for the current assignment list and the cited specifications for exact behavior. ```text 1xx Informational — request progress before a final response 2xx Successful — request received and accepted 3xx Redirection — further action is needed to complete the request 4xx Client error — the request cannot be fulfilled as sent 5xx Server error — the server could not fulfill an apparently valid request ``` ## Successful responses 200 OK means the request succeeded; the response content depends on the request method. 201 Created identifies a newly created resource. 202 Accepted means processing has been accepted but is not complete. 204 No Content succeeds without response content. 206 Partial Content carries the requested range of a representation. Do not parse a body merely because a status is 2xx. A 204 response has no content, while a 202 response does not promise the requested work is finished. ```text 200 OK Request succeeded 201 Created New resource created 202 Accepted Processing accepted, not completed 204 No Content Success with no response content 206 Partial Content A requested representation range ``` ## Redirects and conditional requests 301 and 308 indicate a permanent new URI; 302 and 307 indicate a temporary one. For an automatic redirect, 307 and 308 preserve the request method. Historical behavior allows a client to change POST to GET after 301 or 302. A 303 response directs a client to retrieve another resource, normally with GET. 304 Not Modified is in the 3xx class but is not an instruction to fetch a new URI. It answers a conditional GET or HEAD when the client's stored representation can be reused. Read the response headers before deciding what to fetch or cache. ```text 301 / 308 Permanent new URI 302 / 307 Temporary new URI 303 See another resource 304 Conditional response; reuse a stored representation ``` ## Request and access problems 400 indicates a problem with the request. 401 requires an authentication challenge; 403 means the server refuses the request. 404 means no current representation was found or its existence is not disclosed; 410 is preferable when the server knows the absence is likely permanent. 405 means the method is unsupported for that resource and the response must include Allow. 409 reports a conflict with the resource's current state. 413 means request content is too large; 415 means its media type is unsupported. 429 means too many requests in a period; a Retry-After header may suggest when to try again. Do not treat every 4xx as a missing URL. ```text 400 Bad Request Request problem 401 Unauthorized Authentication challenge 403 Forbidden Request refused 404 Not Found No current representation disclosed 405 Method Not Allowed Method unsupported; inspect Allow 409 Conflict State conflict 410 Gone Likely permanent absence 413 Content Too Large Request content exceeds a limit 415 Unsupported Media Type Content format not accepted 429 Too Many Requests Rate limit; inspect Retry-After if present ``` ## Server and gateway problems 500 indicates an unexpected server failure. 502 and 504 describe gateway or proxy problems with an upstream server: an invalid response and a timeout, respectively. 503 indicates temporary unavailability, such as overload or maintenance, and may include Retry-After. For Waypoint's resource API, a 503 means the fetch failed; it is not an empty fixture. Check the response status before parsing content. Before retrying any request, consider whether repeating its method and body could repeat an effect. ```text 500 Internal Server Error Unexpected server failure 502 Bad Gateway Invalid upstream response 503 Service Unavailable Temporary inability to serve 504 Gateway Timeout Upstream response timed out ``` ## Related - [HTTP headers](/resources/docs/http-headers.md) ## Sources - [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes) - [RFC 9110, HTTP Semantics, Section 15](https://www.rfc-editor.org/rfc/rfc9110.html#section-15) - [RFC 6585, Section 4: 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#section-4)