The number in an API response tells you exactly what happened — if you know how to read it
A 401 comes back and the developer adds the Authorization header. A 403 comes back and they spend an hour wondering why the correct token isn't working. A 301 causes a POST request to silently become a GET. A 422 is confused with 400. Each of these has a specific meaning, and knowing the difference resolves debugging sessions that would otherwise take hours.
HTTP status codes aren't arbitrary. They follow a structured taxonomy, and once you understand the categories and the common codes within each, reading an API response becomes a diagnostic skill rather than a guessing game.
The five categories
Every HTTP status code falls into one of five ranges:
| Range | Category | Meaning |
|---|---|---|
| 1xx | Informational | Request received, processing continues |
| 2xx | Success | Request was received, understood, and accepted |
| 3xx | Redirection | Further action needed to complete the request |
| 4xx | Client error | The request contains an error — fix it on the client side |
| 5xx | Server error | The server failed — the request may have been valid |
The most important distinction for debugging: 4xx = your problem, 5xx = their problem (usually). A 400-series response means something in the request was wrong. A 500-series means the server couldn't handle a request that may have been perfectly valid.
2xx: Success codes
200 OK
The standard success response. The request was processed and the response body contains the result. For GET requests, the body contains the requested resource. For POST, it usually contains the created or processed resource.
201 Created
The request succeeded and a new resource was created. Should include a Location header pointing to the new resource's URL. Expected response to a successful POST that creates a database record. If an API returns 200 instead of 201 for creation, it's technically correct but less precise.
204 No Content
Success — but no response body. Common for DELETE requests, or PUT/PATCH requests where the server doesn't need to return the updated resource. If your code tries to parse the body of a 204 response, it will fail.
202 Accepted
The request was accepted for processing, but processing hasn't completed yet. Used for asynchronous operations — the API queued your job and will process it. Usually includes a way to check status (a job ID, a polling URL, or a webhook callback).
206 Partial Content
The server is returning only part of the resource — used for range requests. Common in video streaming and large file downloads where the client requests specific byte ranges.
3xx: Redirection codes
301 Moved Permanently
The resource has permanently moved to a new URL (provided in the Location header). Critically: most HTTP clients will change POST requests to GET when following a 301. If you're POSTing to an API that returns 301, your body is likely being dropped. Use 308 instead for permanent redirects that preserve the HTTP method.
302 Found (Temporary Redirect)
The resource is temporarily at a different URL. Same method-change caveat as 301 — many clients will convert POST to GET. Use 307 for temporary redirects that must preserve the method.
304 Not Modified
The client sent a conditional GET (with If-Modified-Since or If-None-Match), and the resource hasn't changed. The client should use its cached version. No response body is sent. This is a caching optimisation — the server saves bandwidth by confirming "use what you already have."
307 Temporary Redirect
Like 302, but the HTTP method must be preserved. A POST to a URL returning 307 should be re-posted to the new URL.
308 Permanent Redirect
Like 301, but the method must be preserved. The correct code for permanently redirecting a POST endpoint.
4xx: Client error codes
400 Bad Request
The server couldn't understand the request due to invalid syntax. Common causes: malformed JSON body, missing required fields, wrong Content-Type header, invalid query parameters. The response body usually (should) include details about what was wrong.
401 Unauthorized
Despite the name, this means unauthenticated — you haven't proved who you are. Missing or invalid credentials. Check: is the token present? Is it in the right header format (Authorization: Bearer <token>)? Has it expired?
403 Forbidden
You're authenticated (the server knows who you are) but not authorised for this action. The token is valid; you just don't have permission. Check: does the user have the right role or scope? Is the resource owned by someone else?
401 vs 403: 401 = "I don't know who you are." 403 = "I know who you are, and you can't do this."
404 Not Found
The resource doesn't exist at this URL. Could mean: wrong ID, the resource was deleted, the URL path is wrong, or the API version in the URL is wrong.
405 Method Not Allowed
The URL exists but doesn't support the HTTP method you used. You GETted an endpoint that only accepts POST, or DELETEd something that's read-only. The response should include an Allow header listing the supported methods.
408 Request Timeout
The server didn't receive a complete request within the timeout window. Usually indicates a slow client connection or a very large request body.
409 Conflict
The request couldn't be completed because of a conflict with the current state of the resource. Common examples: trying to create a resource that already exists (duplicate email, duplicate username), or a version conflict in optimistic concurrency control.
410 Gone
Like 404, but the resource explicitly no longer exists and won't be coming back. Use 404 for "I don't know about this," 410 for "this existed and has been permanently removed."
422 Unprocessable Entity
The request was well-formed (valid JSON, correct Content-Type) but the content failed semantic validation. The body was parseable, but the values were invalid — a date in the wrong format, an email that fails validation, a value outside an acceptable range. More specific than 400.
400 vs 422: 400 = can't parse the request at all. 422 = parsed fine, but the values are wrong.
429 Too Many Requests
Rate limiting. The client has sent too many requests in a given period. The response usually includes Retry-After header indicating how long to wait. Implement exponential backoff when you see 429s.
5xx: Server error codes
500 Internal Server Error
Something went wrong on the server that it didn't handle gracefully. An unhandled exception, a null pointer, a misconfigured dependency. Not your fault as the API client — but worth noting the request details so you can report the issue.
501 Not Implemented
The server doesn't support the functionality required to fulfill the request. Less common — usually means a feature is planned but not yet built.
502 Bad Gateway
The server acting as a gateway or proxy received an invalid response from an upstream server. Common with load balancers and reverse proxies. Usually transient — retry after a brief pause. If it persists, the upstream service may be down.
503 Service Unavailable
The server is temporarily unable to handle requests — overloaded, under maintenance, or a dependency is down. Usually temporary. Check the service's status page. Retry with backoff.
504 Gateway Timeout
The gateway didn't receive a timely response from the upstream server. Similar to 502 but specifically a timeout. Indicates the upstream service is slow or unresponsive rather than returning an error.
How to use the REST API Checker on sadiqbd.com
- Enter the URL — any public API endpoint
- Select the HTTP method — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
- Add headers — Authorization, Content-Type, custom headers
- Add a request body — JSON, form data, or raw text for POST/PUT/PATCH
- Send — the response shows status code, headers, and body
The status code is the first thing to look at. It tells you which category of problem you're dealing with before you even read the body.
Debugging by status code: a quick decision tree
Got a 4xx?
- 400: Check the request body and query parameters — something is malformed
- 401: Check credentials — missing, expired, or wrong format
- 403: Check permissions — authenticated but not authorised
- 404: Check the URL path and resource ID
- 405: Check the HTTP method — wrong verb for this endpoint
- 409: Check for duplicates or state conflicts
- 422: Check field values — valid format but invalid content
- 429: Back off and retry — you're being rate limited
Got a 5xx?
- 500: Server bug — note the request and report to the API maintainer
- 502/504: Upstream issue — retry with backoff, check status page
- 503: Service down — retry later, check status page
Got a 3xx?
- Check if your HTTP client is following redirects automatically
- Verify the redirect is preserving your HTTP method and request body
- If the final destination is unexpected, trace the redirect chain
Frequently Asked Questions
What's the difference between 401 and 403? 401 means the server doesn't know who you are — authentication is missing or invalid. 403 means the server knows who you are but won't allow the action — authorisation denied. Send a token to fix a 401; request elevated permissions to fix a 403.
Why does my POST sometimes become a GET after a redirect? HTTP/1.0 defined 302 as "the method may change on redirect," and many clients changed POST to GET as a result. To prevent this, use 307 (temporary) or 308 (permanent) which explicitly require the original method to be preserved.
What should an API return when creating a resource?
201 Created, with a Location header pointing to the new resource and ideally the created resource in the response body. Some APIs return 200 — technically not wrong, but less informative.
What does a HEAD request do? HEAD is identical to GET but the server returns only the headers, not the body. Useful for checking whether a resource exists (without downloading it), verifying cache headers, or getting the Content-Length before downloading a large file.
Is the REST API Checker free? Yes — completely free, no sign-up required.
Status codes are the vocabulary of HTTP communication. Once you can read them fluently, debugging API integrations becomes a much more directed process — you know immediately whether to look at your request, your credentials, your permissions, or the other team's infrastructure.
Try the REST API Checker free at sadiqbd.com — send requests to any API and read the full response including status code, headers, and body.
