HTTP semantics are part of an API contract. Clients use methods and status codes to decide whether to retry, display validation errors, refresh a resource or treat an operation as complete. Returning 200 OK for every outcome forces clients to inspect undocumented message text and makes integrations brittle.
Match method to behavior
GET retrieves a representation and should not create side effects. POST commonly creates a subordinate resource or starts an operation. PUT replaces the target representation and is idempotent when repeated with the same request. PATCH applies a partial change; define whether your patch format replaces values, merges objects or uses explicit operations. DELETE requests removal, although the resource may be retained internally for audit or soft-delete purposes.
Select response codes intentionally
Use 201 Created when a resource is created and include a Location header when its URI is known. Use 204 No Content when the operation succeeded and no response body is needed. Use 400 for malformed requests, 401 when valid authentication is missing, 403 when the authenticated caller is not allowed, 404 when the target is unavailable to that caller, 409 for a state conflict and 422 for syntactically valid input that fails domain validation when that convention is part of your API. Use 429 for rate limiting and 5xx for server-side failures.
Do not mislead clients
A failed payment authorization is not necessarily a server error; it may be a valid business outcome that needs a documented conflict or domain response. A queued background operation is not complete merely because it was accepted. Consider 202 Accepted and provide a status resource clients can poll. Avoid returning stack traces, SQL errors or upstream provider messages in public responses.
Test the contract
Write tests for both the status and the response headers/body. Include edge cases such as missing records, duplicate submissions, expired credentials and validation failures. Confirm that caches and client libraries interpret the selected status correctly.
Further reading
- RFC 9110: Status Codes — https://www.rfc-editor.org/rfc/rfc9110
- RFC 9110: Methods — https://www.rfc-editor.org/rfc/rfc9110