Reference
HTTP Status Codes Reference
HTTP status codes explained for API response debugging, failed fetch calls, redirects, webhook retries and browser network panels.
Overview
HTTP status codes are the first clue when an API response does not match what the frontend or integration expects. This reference focuses on codes developers commonly see while debugging copied responses, failed fetch calls, webhook retries and browser network panels.
Debugging Reference Table
| Code | Meaning | API debugging note |
|---|---|---|
| 200 OK | Request succeeded | The payload can still be malformed, empty or the wrong content type. Validate the response body next. |
| 201 Created | Resource created | Check the response body and Location header when a client expects the new resource ID. |
| 204 No Content | Success with no body | Calling response.json() on a 204 response often causes parsing errors. |
| 301 / 302 | Redirect | Fetch or API clients may follow redirects and receive HTML instead of JSON. |
| 400 Bad Request | Invalid client request | Inspect encoded query values, JSON syntax and required fields. |
| 401 Unauthorized | Missing or invalid authentication | Check Authorization headers, expired tokens and environment-specific credentials. |
| 403 Forbidden | Authenticated but not allowed | Authentication may be valid while permissions, scopes or IP restrictions fail. |
| 404 Not Found | Resource or route missing | Verify base URL, route parameters, deployment environment and trailing slash behavior. |
| 409 Conflict | State conflict | Common for duplicate writes, version mismatches or idempotency problems. |
| 415 Unsupported Media Type | Request body type rejected | Usually caused by missing or wrong Content-Type when sending JSON. |
| 422 Unprocessable Content | Syntax accepted but semantic validation failed | Inspect field-level validation errors in the response payload. |
| 429 Too Many Requests | Rate limit exceeded | Check retry-after headers and whether client retries are too aggressive. |
| 500 Internal Server Error | Server failed unexpectedly | Capture request ID, input payload and server logs if available. |
| 502 / 503 / 504 | Gateway or upstream failure | Often points to proxy, timeout, deployment or upstream API availability issues. |
Reference Table Coverage
- Success responses that still break JSON parsing.
- Authentication and permission failures.
- Payload, validation and content-type errors.
- Rate limits and upstream failures.
API Debugging Examples
- A 204 response causes JSON.parse or response.json() to fail because there is no body.
- A 302 redirect returns an HTML login page to a client expecting JSON.
- A 415 response appears after sending JSON without the application/json Content-Type header.
Common Mistakes
- Treating any 2xx response as parseable JSON.
- Debugging only the body while ignoring status and headers.
- Confusing 401 authentication failures with 403 authorization failures.
- Retrying 429 responses without checking rate-limit headers.
FAQ
Can a 200 response still be an API bug?
Yes. A 200 response only says the request succeeded at the HTTP layer. The body may still be malformed, empty or semantically wrong.
Why does response.json() fail on 204?
A 204 response has no content. The client should skip JSON parsing or handle the empty body explicitly.
What should I check first for a 415 response?
Check the Content-Type header and make sure the request body matches what the API expects.