HTTP status codes and IAM semantics: are your APIs speaking clearly?

TL;DR: HTTP status codes are routinely misused in production APIs, with 200 responses masking failures and 401, 403, 400, 422, 502, 503, and 504 often applied inconsistently, according to WorkOS. Correct semantics preserve authentication, authorization, debugging, and observability boundaries; sloppy status handling turns API contracts into noise.

NHIMG editorial — based on content published by WorkOS: The developer’s guide to HTTP error codes

By the numbers:

• Some APIs respond with 200 OK even when an operation fails, stuffing an error object into the body instead.
• A reverse proxy like Cloudflare or Fastly won’t differentiate between real successes and application errors if everything is 200.

Questions worth separating out

Q: How should security teams handle authentication and authorization errors in APIs?

A: Use 401 when the caller is missing valid credentials or presents an expired token, and use 403 when the identity is known but not allowed to proceed.

Q: When should teams use 400 instead of 422 for request failures?

A: Use 400 when the request cannot be parsed or is structurally invalid, such as malformed JSON or missing required fields.

Q: How do teams know whether an API error is a client issue or a server issue?

A: Use the status code class as the first signal.

Practitioner guidance

• Separate authentication from authorization outcomes Return 401 when credentials are missing or invalid, and 403 when the caller is authenticated but not permitted.
• Reserve 400 for parsing failures and 422 for semantic violations Use 400 when the server cannot parse the request, and 422 when the payload is syntactically valid but fails a business rule.
• Propagate the most specific 5xx code available Preserve 502, 503, and 504 instead of normalizing every upstream issue into 500.

What's in the full article

WorkOS's full article covers the operational detail this post intentionally leaves for the source:

• Exact RFC 9110 references and the reasoning behind each status code choice for common API scenarios
• Concrete examples of headers such as WWW-Authenticate and Retry-After in authentication and throttling flows
• A fuller decision table for mapping validation, authorization, and dependency failures to specific HTTP responses
• Implementation guidance for propagating upstream failure details through gateways and proxies

👉 Read WorkOS's guide to correct HTTP status code usage →

HTTP status codes and IAM semantics: are your APIs speaking clearly?

Explore further

View Full Forum →  |  NHI Foundation Course →