HTTP status codes in a client-facing service

Returning 200 with an error string forces every client to interpret prose. Status codes and structured error bodies let callers decide whether to correct, authenticate, retry or stop.

Review an outcome map

The engineering foundations lab defines fixture semantics.

from engineering_cases import status_code_case

result = status_code_case()
assert result["mapping"]["created"] == 201
assert result["mapping"]["invalid_input"] == 422
assert result["mapping"]["conflict"] == 409
assert result["mapping"]["dependency_unavailable"] == 503
assert result["unique"] is True

Use 401 when authentication is missing/invalid and 403 when identity is known but forbidden. Use 404 for absent/hidden resources, 409 for state conflict, 429 for throttling and 503 for temporary unavailability. Choose 400/422 validation policy consistently and document it.

Return a stable machine code, safe detail, field errors, request ID and retry information when relevant. Do not expose stack traces or secrets. Test client behaviour for each code, including whether retries are bounded.

The FDE for Freshers course applies HTTP contracts to FastAPI and third-party integrations.

Exercise

Define outcomes for an order endpoint and implement a Problem Details-style error schema. Write a client test proving only retryable statuses are retried.

Continue learning

This article is part of the FDE engineering foundations sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Environment variables: separate configuration and secrets.
• Continue with JSON schema validation at an API boundary.

References: HTTP Semantics RFC 9110 and Problem Details RFC 9457.