LEARN. PRACTICE. GROW.Concept and mechanism
Method, headers, and body communicate intent and representation. Content-Type identifies sent content; Accept describes response preferences. Choosing a method only from an internal function name weakens contract clarity. A read operation should not hide an irreversible business action that an intermediary may repeat. The HTTP outcome should match what the responding layer knows. An asynchronous acceptance response does not establish work completion. Define how to obtain status, distinguish final failure from waiting, and determine when consumers should stop polling.
Guided application
In a fictional exercise, creating a request returns 202 and a reference for tracking processing. The dashboard immediately marks the request settled even though the worker has not processed it. Correct this by modeling states and checking the final outcome while retaining the reference for diagnosis. For errors, Problem Details provides a consistent structure and specific extensions. Body status does not replace the actual response code. Use occurrence identifiers and useful messages without stack traces or sensitive content. Clients should handle error categories and types defined by the contract rather than depend on a translated phrase that can change across versions.
Accepted, processing, and completed are different operation-tracking states.
Common pitfalls
202 as completion; errors inside 200 as transparent contracts; human messages as stable identifiers.
Related topics: API resources and contracts · Concurrency and retries · Authorization and boundaries
Connect each response to a concrete consumer decision.
Reference: RFC9457 Problem Details for HTTP APIs · HTTP semantics RFC9110; OpenAPI3.2.1; selected primary standards and provider contracts consulted2026-09-30