Browse cheat sheets · APIs

Technology: APIsCategory: HTTP & API DesignDifficulty: IntermediateUpdated

HTTP Status Codes for Developers

Interpret and use HTTP status codes correctly when building and troubleshooting APIs, with practical guidance for success, redirects, client errors, server errors, retries, and API design decisions.

On this page
  1. Problem
  2. Quick answer
  3. Code / commands
  4. 1. Inspect the status code with cURL
  5. 2. Inspect headers and body together
  6. 3. Fail scripts on HTTP errors
  7. 4. 200 OK
  8. 5. 201 Created
  9. 6. 202 Accepted
  10. 7. 204 No Content
  11. 8. 206 Partial Content
  12. 9. 301 Moved Permanently
  13. 10. 302 Found
  14. 11. 303 See Other
  15. 12. 304 Not Modified
  16. 13. 307 Temporary Redirect
  17. 14. 308 Permanent Redirect
  18. 15. 400 Bad Request
  19. 16. 401 Unauthorized
  20. 17. 403 Forbidden
  21. 18. 404 Not Found
  22. 19. 405 Method Not Allowed
  23. 20. 406 Not Acceptable
  24. 21. 408 Request Timeout
  25. 22. 409 Conflict
  26. 23. 410 Gone
  27. 24. 412 Precondition Failed
  28. 25. 413 Content Too Large
  29. 26. 414 URI Too Long
  30. 27. 415 Unsupported Media Type
  31. 28. 422 Unprocessable Content
  32. 29. 428 Precondition Required
  33. 30. 429 Too Many Requests
  34. 31. 431 Request Header Fields Too Large
  35. 32. 500 Internal Server Error
  36. 33. 501 Not Implemented
  37. 34. 502 Bad Gateway
  38. 35. 503 Service Unavailable
  39. 36. 504 Gateway Timeout
  40. 37. Distinguish 408 from 504
  41. 38. Distinguish 400 from 422
  42. 39. Distinguish 409 from 422
  43. 40. Distinguish 401 from 403
  44. 41. Distinguish 404 from empty collections
  45. 42. Do not return 404 for an empty search by default
  46. 43. Use 201 for creation, not every POST
  47. 44. Use 204 only when no body is needed
  48. 45. Use 202 for real asynchronous processing
  49. 46. Use Location for created or asynchronous resources when useful
  50. 47. Use ETags for optimistic concurrency
  51. 48. Return machine-readable errors
  52. 49. Do not expose stack traces
  53. 50. Include a request/correlation ID
  54. 51. Preserve useful upstream status carefully
  55. 52. Do not blindly forward every upstream status
  56. 53. Retry only statuses that fit the operation
  57. 54. Do not retry most 4xx errors blindly
  58. 55. 409 may or may not be retryable
  59. 56. Respect Retry-After
  60. 57. Back off instead of retrying in a tight loop
  61. 58. Use idempotency keys for retryable creates when supported
  62. 59. Check where the status originated
  63. 60. Check Content-Type on errors
  64. 61. Log status by endpoint and caller identity safely
  65. 62. Monitor status classes, not only 500
  66. 63. Separate expected 4xx from server defects
  67. 64. Investigate sudden 401 spikes
  68. 65. Investigate sudden 403 spikes
  69. 66. Investigate sudden 404 spikes
  70. 67. Investigate 429 by identity and endpoint
  71. 68. Investigate 500 with request IDs
  72. 69. Investigate 502 against upstream connectivity
  73. 70. Investigate 503 against availability and overload
  74. 71. Investigate 504 against dependency latency
  75. 72. Do not turn every exception into 400
  76. 73. Do not turn every failure into 500
  77. 74. Keep status semantics stable across versions
  78. 75. Use status plus domain error code
  79. 76. Avoid inventing dozens of HTTP-like numeric codes
  80. 77. Document retry behavior
  81. 78. Use a troubleshooting sequence
  82. What the result means
  83. What to look for
  84. 401 across all clients
  85. 403 only for one operation
  86. 404 after a deployment
  87. 409 during concurrent updates
  88. 422 with otherwise valid JSON
  89. 429 followed by even more traffic
  90. 502 / 504 only through the gateway
  91. 500 with HTML instead of JSON
  92. Production notes
  93. Status codes are part of the API contract
  94. Do not use status code alone for observability
  95. Retry behavior is a distributed-systems decision
  96. Gateways can rewrite responses
  97. Security can intentionally affect status choice
  98. Common mistakes
  99. 1. Reading 401 as “authenticated but unauthorized”
  100. 2. Returning 500 for validation errors
  101. 3. Returning 200 with { "success": false } for every failure
  102. 4. Retrying every 5xx
  103. 5. Retrying every 409
  104. 6. Treating 202 as completed success
  105. 7. Sending a body with 204
  106. 8. Using 206 for normal API pagination
  107. 9. Assuming every 502/504 came from application code
  108. 10. Exposing internal exception details in 500 responses
  109. Next step
  110. Related deep dives

Problem

An API returned 400, 401, 404, 409, 429, or 500, and you need to know what that actually tells you.

Status codes are useful only when interpreted with context.

A good troubleshooting process separates:

  • request syntax problems
  • authentication failures
  • authorization failures
  • missing resources
  • state conflicts
  • validation errors
  • rate limits
  • gateway failures
  • application failures
  • temporary service availability problems

The goal is to use the status code as a routing signal for the next investigation, not as the complete diagnosis.

Quick answer

Use the status-code class first:

1xx
→ informational

2xx
→ request succeeded

3xx
→ redirect / cache-related response

4xx
→ the request cannot be completed as sent

5xx
→ the server or an upstream service failed to complete a valid request

For common API failures:

400
→ malformed or invalid request

401
→ authentication missing or invalid

403
→ authenticated but not allowed

404
→ resource or route not found

409
→ request conflicts with current resource state

412
→ precondition failed

415
→ unsupported request media type

422
→ syntactically valid request but semantic/validation failure

429
→ rate limit / too many requests

500
→ unexpected server failure

502
→ upstream returned an invalid/failing response

503
→ service temporarily unavailable

504
→ upstream timed out

Always inspect:

status
+
response headers
+
response body
+
request ID/correlation ID

before deciding where the fault is.

Code / commands

1. Inspect the status code with cURL

curl \
  --silent \
  --output response.json \
  --write-out "%{http_code}\n" \
  "https://api.example.com/v1/reports"

This saves the body separately and prints the HTTP status.


2. Inspect headers and body together

curl \
  --include \
  "https://api.example.com/v1/reports"

Useful for interactive troubleshooting.

Look for:

  • Content-Type
  • Retry-After
  • WWW-Authenticate
  • cache headers
  • gateway/proxy headers
  • request/correlation IDs

3. Fail scripts on HTTP errors

curl \
  --silent \
  --show-error \
  --fail-with-body \
  "https://api.example.com/v1/reports"

Without --fail*, cURL may return process exit code 0 even when the HTTP response is 404 or 500.


4. 200 OK

Typical uses:

successful GET
successful synchronous update
successful action with response body

Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reportId": "rpt-123",
  "status": "ready"
}

Use when the request succeeded and a normal response representation is returned.


5. 201 Created

Use when the request successfully creates a new resource.

Typical response:

HTTP/1.1 201 Created
Location: /v1/reports/rpt-123
Content-Type: application/json
{
  "reportId": "rpt-123"
}

When practical, return a Location header identifying the created resource.


6. 202 Accepted

Use when the server accepts the request but processing will happen asynchronously.

Example:

HTTP/1.1 202 Accepted
Location: /v1/jobs/job-456
{
  "jobId": "job-456",
  "status": "queued"
}

202 does not mean the background operation has completed successfully.

Provide a status resource or callback/event mechanism when the caller needs the final outcome.


7. 204 No Content

Use when the request succeeds and there is intentionally no response body.

Common uses:

successful DELETE
successful update where no representation is returned

Example:

HTTP/1.1 204 No Content

Do not send a JSON body with a 204 response.


8. 206 Partial Content

Used for successful range requests.

Typical scenario:

large file download
media streaming
resumable transfer

The response includes range-related headers such as Content-Range.

Do not use 206 merely because an API returns part of a logical dataset through pagination.


9. 301 Moved Permanently

Use for a permanent redirect when appropriate.

Clients may cache permanent redirects.

For APIs, be cautious with method behavior and client compatibility when redirecting non-GET requests.


10. 302 Found

A temporary redirect historically used widely by browsers and servers.

Client method behavior across redirects can differ depending on context.

For APIs where preserving the original method matters, 307 or 308 is usually clearer.


11. 303 See Other

Useful after an operation when the client should retrieve another resource with GET.

Example:

POST creates/starts operation
→ 303
→ GET result/status URL

12. 304 Not Modified

Used with conditional requests.

Example request:

If-None-Match: "abc123"

Possible response:

HTTP/1.1 304 Not Modified

This tells the client its cached representation can still be used.

304 is not a normal success response with a body.


13. 307 Temporary Redirect

Temporary redirect that preserves the HTTP method and request body.

Useful when an API request must be repeated at another URI without changing POST/PUT/PATCH into GET semantics.


14. 308 Permanent Redirect

Permanent redirect that preserves method and body semantics.

Use carefully because permanent redirects may be cached.


15. 400 Bad Request

Use when the request is malformed or cannot be processed because of client-provided request syntax/data.

Examples:

invalid JSON
missing required field
bad query parameter syntax
invalid date format

Example body:

{
  "error": "invalid_request",
  "message": "startDate must use YYYY-MM-DD"
}

Do not return 500 for a validation problem the client can correct.


16. 401 Unauthorized

Despite the name, 401 normally means:

authentication required, missing, or invalid

Examples:

  • missing Bearer token
  • expired token
  • invalid signature
  • wrong token issuer/audience
  • invalid API credential

For HTTP authentication schemes, include an appropriate WWW-Authenticate challenge when applicable.


17. 403 Forbidden

Use when the server understands the request and the caller is authenticated or otherwise identified, but access is not allowed.

Examples:

  • missing required scope
  • wrong role
  • tenant policy denies access
  • resource ownership check fails

Normal distinction:

401
→ who are you / your credential is invalid

403
→ we know who you are, but you cannot do this

18. 404 Not Found

Use when the requested resource or route is not found.

Examples:

unknown report ID
wrong path
deleted resource
unknown API version route

Some APIs intentionally return 404 instead of 403 to avoid revealing whether a protected resource exists.


19. 405 Method Not Allowed

Use when the route exists but does not support the requested HTTP method.

Example:

GET /reports/123
→ supported

POST /reports/123
→ not supported

A response should generally include an Allow header identifying supported methods.


20. 406 Not Acceptable

Use when the server cannot produce a representation acceptable according to the client’s Accept header.

Example:

Accept: application/xml

when the API only supports JSON.

This is less common in APIs that expose one fixed response format.


21. 408 Request Timeout

Indicates the server timed out waiting for the client’s request.

Do not confuse it with:

504 Gateway Timeout

which means a gateway/proxy timed out waiting for an upstream service.


22. 409 Conflict

Use when the request conflicts with the current state of the resource.

Good examples:

duplicate unique business key
version/state conflict
resource already exists under a uniqueness rule
operation invalid in current lifecycle state

Example:

{
  "error": "state_conflict",
  "message": "Report is already finalized."
}

409 is often a better fit than generic 400 when the problem is specifically current resource state.


23. 410 Gone

Use when a resource previously existed but has intentionally been removed and the server wants to communicate that the absence is permanent.

Do not use it unless that distinction from 404 is operationally meaningful.


24. 412 Precondition Failed

Used when a conditional request precondition fails.

Example optimistic concurrency request:

If-Match: "version-42"

If the resource now has a different ETag:

HTTP/1.1 412 Precondition Failed

This is useful for preventing lost updates.


25. 413 Content Too Large

Use when the request body exceeds limits accepted by the server or intermediary.

Typical causes:

  • file too large
  • JSON payload too large
  • proxy/gateway request-body limit

The failure may occur before the application receives the request.


26. 414 URI Too Long

Use when the request URI exceeds what the server or intermediary accepts.

Common cause:

placing a very large filter/list into query parameters

Move large structured input into an appropriate request body when API semantics allow it.


27. 415 Unsupported Media Type

Use when the request Content-Type is unsupported.

Example:

Content-Type: application/xml

against an endpoint that only accepts:

application/json

Check the actual request header, not just what the client code intended to send.


28. 422 Unprocessable Content

Use when the request syntax/media type is valid but the content cannot be processed semantically.

Example:

{
  "startDate": "2026-11-01",
  "endDate": "2026-10-01"
}

Possible response:

HTTP/1.1 422 Unprocessable Content
{
  "error": "validation_failed",
  "fields": {
    "endDate": "Must be on or after startDate"
  }
}

Some APIs use 400 for all validation failures. Consistency matters more than forcing every validation rule into 422.


29. 428 Precondition Required

Use when the server requires a conditional request to prevent lost updates.

Example requirement:

If-Match: "etag-value"

This can enforce optimistic concurrency.


30. 429 Too Many Requests

Use when the caller exceeded a rate/concurrency quota.

Typical response:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Client response:

respect Retry-After
reduce concurrency
use bounded backoff
avoid retry storms

Do not hammer the service faster after receiving 429.


31. 431 Request Header Fields Too Large

Used when request headers are too large.

Common causes:

  • oversized cookies
  • very large JWTs
  • repeated proxy headers
  • excessive custom headers

The request may be rejected by a gateway before reaching the application.


32. 500 Internal Server Error

Use for unexpected server-side failures when a more specific status does not apply.

Examples:

unhandled exception
unexpected invariant failure
internal bug

Do not expose stack traces, secrets, SQL, or internal paths in the client-facing response.

Return a correlation/request ID for support.


33. 501 Not Implemented

Means the server does not support the functionality required to fulfill the request.

This is not normally the right status for:

feature flag disabled
endpoint temporarily unavailable
resource-specific unsupported state

Use it only when the server genuinely does not implement the requested capability.


34. 502 Bad Gateway

A gateway/proxy received an invalid or failed response from an upstream server.

Typical architecture:

client
→ API gateway
→ backend

If the gateway cannot get a valid backend response:

502

Investigate the gateway-to-upstream path.


35. 503 Service Unavailable

Use when the service is temporarily unable to handle requests.

Examples:

  • maintenance
  • overloaded dependency
  • unavailable backend pool
  • intentional load shedding

A Retry-After header may be useful when the server knows when retrying is appropriate.


36. 504 Gateway Timeout

A gateway/proxy did not receive a timely response from an upstream service.

Typical path:

client
→ gateway
→ slow backend/dependency

Do not assume the gateway itself is the root cause.

Inspect upstream latency and timeout configuration.


37. Distinguish 408 from 504

408
→ server timed out waiting for the client request

504
→ gateway timed out waiting for an upstream response

This distinction helps identify which direction of the request path stalled.


38. Distinguish 400 from 422

One useful API convention:

400
→ malformed request / parsing / structural validation

422
→ structurally valid request with invalid business/semantic values

This is a design convention, not a requirement for every API.

Choose a consistent error model and document it.


39. Distinguish 409 from 422

Use 409 when the failure is mainly about current resource state:

version conflict
duplicate state
invalid lifecycle transition because resource changed

Use 422 when the request content itself fails semantic validation.

There can be overlap. Consistency matters.


40. Distinguish 401 from 403

Do not use:

403 for every auth error

A clearer pattern is:

missing/invalid authentication
→ 401

authenticated but insufficient permission
→ 403

41. Distinguish 404 from empty collections

Request:

GET /reports?merchant=abc

with no matching reports can reasonably return:

200 OK
[]

The collection endpoint exists; its result is empty.

By contrast:

GET /reports/nonexistent-id

may return:

404

42. Do not return 404 for an empty search by default

An empty collection is usually a valid result, not a missing endpoint/resource.

This distinction simplifies client behavior.


43. Use 201 for creation, not every POST

POST does not automatically mean 201.

Examples:

POST /reports
creates report resource
→ 201

POST /reports/123/run
starts asynchronous execution
→ 202

POST /search
returns query results
→ 200

Choose status by outcome, not HTTP method alone.


44. Use 204 only when no body is needed

If you need to return:

{
  "status": "deleted"
}

then 200 may be more appropriate.

A 204 response should not carry a message body.


45. Use 202 for real asynchronous processing

Do not return 202 merely to hide slow synchronous work.

A good async contract should give the caller a way to determine completion:

job URL
status endpoint
webhook
event

46. Use Location for created or asynchronous resources when useful

Creation:

HTTP/1.1 201 Created
Location: /v1/reports/rpt-123

Async:

HTTP/1.1 202 Accepted
Location: /v1/jobs/job-456

This makes the next client action explicit.


47. Use ETags for optimistic concurrency

Read:

ETag: "42"

Update:

If-Match: "42"

If the resource changed:

412 Precondition Failed

This avoids silent lost updates.


48. Return machine-readable errors

Prefer:

{
  "error": "validation_failed",
  "message": "Request validation failed.",
  "fields": {
    "startDate": "Required"
  },
  "requestId": "req-123"
}

over:

Something went wrong

Keep error contracts stable enough for clients to act on them.


49. Do not expose stack traces

Bad production response:

{
  "error": "NullReferenceException at InternalService.cs:842"
}

Return a safe external error plus request ID.

Keep detailed diagnostics in protected server logs.


50. Include a request/correlation ID

Example:

{
  "error": "internal_error",
  "message": "The request could not be completed.",
  "requestId": "req-123"
}

The same ID should appear in server/gateway telemetry when possible.


51. Preserve useful upstream status carefully

If your API calls another service, do not blindly translate every upstream error into:

500

Examples:

upstream timeout through gateway
→ perhaps 504

upstream unavailable
→ perhaps 503

client supplied invalid resource ID
→ perhaps preserve meaningful 4xx behavior

But do not leak internal dependency details unnecessarily.


52. Do not blindly forward every upstream status

Your API owns its public contract.

An internal service may return a status that does not make sense to your external client.

Translate deliberately while keeping server-side observability of the original upstream result.


53. Retry only statuses that fit the operation

Potentially retryable conditions often include:

429
502
503
504

depending on the API and operation.

But retry safety also depends on:

HTTP method
idempotency
request side effects
Retry-After
provider guidance

Do not use a universal retry list.


54. Do not retry most 4xx errors blindly

Examples:

400
401
403
404
415
422

usually require the request, credential, permission, or resource to change.

A retry with the same input usually repeats the same failure.


55. 409 may or may not be retryable

Examples:

optimistic concurrency conflict
→ reload resource and retry with new version

duplicate key
→ retrying same create request is not useful

temporary state transition conflict
→ maybe retry after state changes

Interpret the error body and business contract.


56. Respect Retry-After

Retry-After may be returned with statuses such as:

429
503

Clients should use it when present and valid rather than immediately retrying.


57. Back off instead of retrying in a tight loop

Bad:

request fails
→ immediate retry
→ immediate retry
→ immediate retry

This can worsen overload.

Use bounded backoff with jitter where appropriate.


58. Use idempotency keys for retryable creates when supported

Example:

Idempotency-Key: 5f1b...

If the API supports it, the server can recognize repeated create attempts and avoid duplicate side effects.

The mechanism must be implemented by the server; a random header alone does nothing.


59. Check where the status originated

A 502, 503, or 504 may come from:

  • CDN
  • WAF
  • load balancer
  • API gateway
  • reverse proxy
  • application

Inspect headers and body.

Do not assume the application generated every response.


60. Check Content-Type on errors

Expected:

application/json

Received:

text/html

This often suggests an intermediary generated an error page.

Use:

curl --include ...

to inspect it.


61. Log status by endpoint and caller identity safely

Useful dimensions:

route
method
status class
status code
client/application identity
tenant
latency
request ID

Avoid logging credentials or sensitive request payloads.


62. Monitor status classes, not only 500

Useful operational views:

2xx rate
4xx rate
5xx rate
429 rate
latency by status

A sudden rise in 401, 403, 404, or 429 can indicate a production problem even if 500 remains low.


63. Separate expected 4xx from server defects

A validation-heavy endpoint may legitimately return many 400/422 responses.

Operationally distinguish:

expected rejected input
from
unexpected client integration breakage

Baseline by endpoint and client.


64. Investigate sudden 401 spikes

Possible causes:

  • expired signing key/certificate
  • bad deployment configuration
  • token audience change
  • clock problem
  • auth provider outage
  • client credential rotation failure

A 401 spike across many clients is different from one user’s expired token.


65. Investigate sudden 403 spikes

Possible causes:

  • authorization policy change
  • scope/role deployment
  • tenant mapping defect
  • gateway policy update

Authentication may still be healthy.


66. Investigate sudden 404 spikes

Possible causes:

  • client switched to wrong API version
  • route deployment changed
  • base URL incorrect
  • tenant/resource IDs malformed
  • gateway routing issue

Not every 404 means data was deleted.


67. Investigate 429 by identity and endpoint

Check:

which API key/client/user
which endpoint
request rate
request concurrency
retry behavior

A single aggressive caller can create disproportionate load.


68. Investigate 500 with request IDs

The client-facing message should remain safe.

Use the request ID to find:

exception
dependency call
database query
pipeline step

in protected telemetry.


69. Investigate 502 against upstream connectivity

Check:

backend health
connection reset
invalid upstream response
TLS to backend
proxy/gateway logs

70. Investigate 503 against availability and overload

Check:

healthy backend count
deployment/maintenance
resource saturation
load shedding
dependency outage

71. Investigate 504 against dependency latency

Check:

gateway timeout
backend duration
database duration
downstream API duration
queueing

Increasing the timeout may hide the symptom without fixing the slow dependency.


72. Do not turn every exception into 400

An unexpected database failure is not a client input error.

Return a server-side status when the server failed.

Misclassifying errors makes monitoring and client behavior worse.


73. Do not turn every failure into 500

Known client errors should use meaningful 4xx responses.

This lets clients correct behavior without treating everything as an outage.


74. Keep status semantics stable across versions

If:

duplicate create

returns 409 in one endpoint and 500 in another, client behavior becomes harder to implement.

Consistency improves API usability and operations.


75. Use status plus domain error code

Example:

HTTP/1.1 409 Conflict
{
  "error": "report_already_finalized",
  "message": "The report cannot be modified after finalization."
}

HTTP status gives broad meaning.

Domain error code gives precise machine-readable meaning.


76. Avoid inventing dozens of HTTP-like numeric codes

Use standard HTTP status for transport/API semantics.

Add a stable domain error field when additional detail is required.


77. Document retry behavior

For each important error contract, document:

status
domain error
retryable?
requires new token?
requires new resource version?
safe to retry automatically?

This is more useful than publishing a status-code list alone.


78. Use a troubleshooting sequence

1. Capture HTTP status
2. Capture cURL/client exit error separately
3. Read response body
4. Inspect response headers
5. Capture request ID
6. Identify responding layer
7. Determine client vs server responsibility
8. Decide whether retry is safe
9. Correlate server-side telemetry

What the result means

Code Practical interpretation
200 Request completed successfully
201 Resource created
202 Accepted for asynchronous processing
204 Success with no response body
304 Cached representation still valid
400 Bad/malformed/invalid request
401 Authentication missing or invalid
403 Caller not allowed
404 Route/resource not found
405 HTTP method not allowed for route
409 Conflict with current resource state
412 Conditional request precondition failed
413 Request body too large
415 Unsupported request media type
422 Semantic/validation failure
429 Rate limit exceeded
500 Unexpected server failure
502 Gateway received bad upstream response
503 Service temporarily unavailable
504 Gateway timed out waiting for upstream

The status code is a classification signal.

The response body, headers, request context, and server telemetry provide the diagnosis.

What to look for

401 across all clients

Suspect shared authentication infrastructure or configuration before assuming every credential expired independently.

403 only for one operation

Check required role/scope/resource permission.

404 after a deployment

Check routing/version/base path before assuming the data disappeared.

409 during concurrent updates

Look for optimistic-concurrency or state-transition conflicts.

422 with otherwise valid JSON

Inspect field/business validation rules.

429 followed by even more traffic

The client retry policy may be creating a retry storm.

502 / 504 only through the gateway

Compare direct backend health and gateway-to-backend connectivity/latency where architecture permits.

500 with HTML instead of JSON

An intermediary may have generated the response.

Inspect headers to identify the responding layer.

Production notes

Status codes are part of the API contract

Changing them can break:

  • retry behavior
  • monitoring
  • SDK logic
  • UI behavior
  • alerting

Treat status semantics as versioned behavior.

Do not use status code alone for observability

Record:

domain error code
request ID
endpoint
caller identity
latency
upstream dependency

where appropriate.

Retry behavior is a distributed-systems decision

A status may look transient, but retrying a non-idempotent operation can duplicate side effects.

Combine status semantics with idempotency guarantees.

Gateways can rewrite responses

The application may return one result while:

  • gateway
  • proxy
  • CDN
  • WAF

changes the externally visible status/body.

Troubleshoot the full request path.

Security can intentionally affect status choice

Some APIs return 404 instead of 403 to avoid revealing protected-resource existence.

Document and test the chosen policy.

Common mistakes

1. Reading 401 as “authenticated but unauthorized”

In normal HTTP API usage, that situation is usually 403.

2. Returning 500 for validation errors

Clients cannot distinguish bad input from service failure.

3. Returning 200 with { "success": false } for every failure

This hides failure semantics from HTTP clients, gateways, and monitoring.

4. Retrying every 5xx

Retry may be unsafe or may worsen overload.

5. Retrying every 409

Conflict meaning is domain-specific.

6. Treating 202 as completed success

It only means the request was accepted.

7. Sending a body with 204

204 means no response content.

8. Using 206 for normal API pagination

206 is for HTTP partial-content/range semantics, not ordinary page-based datasets.

9. Assuming every 502/504 came from application code

Gateways often generate them.

10. Exposing internal exception details in 500 responses

Use safe errors plus a request ID.

Next step

Use the status to route the investigation.

  • 400 / 415 / 422 → inspect request syntax, content type, and validation.
  • 401 → inspect authentication token/key/certificate and issuer/audience/expiry.
  • 403 → inspect scope, role, tenant, and resource authorization.
  • 404 → verify route, API version, resource ID, and gateway routing.
  • 409 / 412 → inspect state/version/concurrency logic.
  • 429 → inspect caller rate, concurrency, Retry-After, and retry policy.
  • 500 → correlate request ID with application logs.
  • 502 → inspect gateway-to-upstream connectivity/response.
  • 503 → inspect service availability, overload, maintenance, and dependencies.
  • 504 → inspect upstream latency and timeout boundaries.
  • Status is unclear or inconsistent → reproduce with cURL and inspect full headers/body.
  • Need end-to-end troubleshooting → move to Troubleshoot API Requests.

← All cheat sheets