NexisyTech Learningby Nexisy Technologies

HTTP Status Codes for APIs

Return the right status code so clients, proxies and monitoring understand what happened.

Beginner6 min read3 interview questions

Status codes are part of the API contract. Clients branch on them, retries depend on them and dashboards count them. Returning 200 OK with an error message in the body breaks all three.

The first digit says who should act: 2xx success, 3xx look elsewhere, 4xx the client must fix the request, 5xx the server failed.

Diagram

2xx Success200 · 201 · 202 · 2043xx Redirect301 · 302 · 3044xx Client error400 · 401 · 403 · 404 · 409 · 4295xx Server error500 · 502 · 503 · 504Safe to retry with backoff429, 503, 504 (and idempotent calls)
The four families of status codes that matter for APIs.

Key concepts

200 / 201 / 204
OK; Created (with a Location header); No Content (e.g. after DELETE).
202 Accepted
Request queued for asynchronous processing.
304 Not Modified
The cached copy is still valid (used with ETag).
400 / 422
Malformed request / well-formed but fails validation.
401 vs 403
401: not authenticated (no or bad token). 403: authenticated but not allowed.
404 / 409
Not found / conflicts with current state (e.g. duplicate, version mismatch).
429
Too many requests — include Retry-After.
500 / 502 / 503 / 504
Unhandled error / bad upstream response / temporarily unavailable / upstream timeout.

Trade-offs

Benefits

  • Clients can handle errors generically
  • Proxies, caches and retry libraries behave correctly
  • Monitoring can alert on 5xx rates

Costs

  • Teams disagree on edge cases — document your choices

Use it when

  • Every HTTP API. Pair status codes with a consistent error body such as RFC 9457 Problem Details.

Common mistakes

  • 200 OK with { "error": … } in the body
  • Returning 500 for validation errors
  • Returning 403 instead of 404 for resources the caller must not know exist

Interview questions

Q1When should an API return 404 instead of 403?
When revealing that a resource exists would leak information — for example another tenant’s record. Returning 404 hides its existence.
Q2Which errors should a client retry?
Transient ones: 429 (after Retry-After), 502, 503, 504 and network timeouts — and only for idempotent operations or with an idempotency key.
Q3What should a POST that creates a resource return?
201 Created with a Location header pointing to the new resource, and usually the resource in the body.

Related lessons

APIs & Security

Idempotency & Preventing Double Payments

Make retries safe, so a timeout never charges a customer twice.

Advanced9 min read APIs & Security

API Architecture Styles

REST, GraphQL, gRPC, WebSockets, webhooks and SOAP — what each is for.

Beginner10 min read APIs & Security

API Security Essentials

Defence in depth for APIs: transport, identity, authorization, input and abuse controls.

Intermediate10 min read