HTTP status codes are one of the most important language contracts between your API and every consumer. Use them inconsistently, and debugging becomes expensive. Use them well, and your system communicates clearly under both success and failure.

The 5 Status Code Families

• 1xx Informational
• 2xx Success
• 3xx Redirection
• 4xx Client errors
• 5xx Server errors

For most JSON APIs, your daily focus is 2xx, 4xx, and 5xx.

Core Codes You Should Standardize

Success

• 200 OK — successful read/update response
• 201 Created — resource created
• 202 Accepted — async work accepted
• 204 No Content — success with no body

Client errors

• 400 Bad Request — malformed or invalid request format
• 401 Unauthorized — missing/invalid authentication
• 403 Forbidden — authenticated but not allowed
• 404 Not Found — resource absent
• 409 Conflict — state conflict (duplicate, version mismatch)
• 422 Unprocessable Entity — semantic validation errors
• 429 Too Many Requests — rate limit exceeded

Server errors

• 500 Internal Server Error — unhandled server failure
• 502 Bad Gateway — upstream dependency failure
• 503 Service Unavailable — temporary outage/maintenance
• 504 Gateway Timeout — upstream timeout

Common API Design Mistakes

Returning 200 for all outcomes

This hides real failure semantics.

Mixing 400 and 422 randomly

Decide a rule and document it.

Returning 500 for user validation errors

Validation should be 4xx, not 5xx.

Missing machine-readable error body

Status alone is not enough. Return structured error payloads.

Error Body Pattern to Reuse

A consistent shape helps every client:

• code (stable programmatic identifier)
• message (human-readable)
• details (field errors or context)
• requestId (for support/debugging)

Status Code Testing Workflow

1. Exercise endpoints with API Tester
2. Validate error payload JSON in JSON Formatter
3. Verify auth token behavior using JWT Decoder

This workflow catches contract drift quickly.

Which Code for Validation: 400 or 422?

A practical policy:

• Use 400 for malformed structure (invalid JSON, wrong content type)
• Use 422 for semantically valid JSON with business-rule failures

Most important: document and enforce consistency.

FAQ

Should login failure be 401 or 403?

Usually 401 for invalid credentials. Use 403 when identity is known but access is denied.

When should I use 202?

When processing is asynchronous and not completed yet.

Is 404 better than 403 for hidden resources?

Depends on threat model. Some systems intentionally return 404 to avoid resource enumeration.

Should every 5xx include stack traces?

No. Return safe error responses; keep stack traces in internal logs.

Final Take

Status codes are not “just protocol details.” They are product-level UX for developers and integrators. A clean status-code contract reduces support load and speeds up integration.

Use API Tester to verify behavior and enforce consistency before shipping.