HTTP API Methods: Safety, Idempotency, and Status Codes
Understand GET, POST, PUT, PATCH and DELETE semantics, safe retries, idempotency, and useful HTTP response codes.
HTTP method semantics affect API safety, retries, caching, and client behavior. GET and POST are not interchangeable labels: safe methods are intended to read, while idempotent methods can be repeated without changing the intended server result. This practical guide explains common methods and response codes using the HTTP Semantics standard.
Safe and idempotent describe different things
A safe method is defined as read-only from the client's requested point of view. An idempotent method has the same intended server effect when the same request is applied more than once. Idempotency does not mean every response must be byte-for-byte identical; logs and timestamps may still change.
Under HTTP semantics, GET, HEAD, and OPTIONS are safe and idempotent. PUT and DELETE are idempotent but not safe. POST is neither safe nor idempotent by default. PATCH does not have a general guarantee of idempotency; it depends on the patch operation and API design.
Choose a method that matches the operation
- GET: retrieve a representation. Do not make a GET link perform a state-changing action; browsers, crawlers, caches, or prefetchers may request it automatically.
- POST: submit data for processing or create a subordinate resource when the server assigns its identifier. Repeating a POST can create duplicate effects unless the API provides an explicit deduplication mechanism.
- PUT: create or replace the state of the resource at the target URI. Repeating the same intended replacement should not create additional effects.
- PATCH: apply a partial modification. Whether it is idempotent depends on the patch document; “set quantity to 4” can be repeatable, while “increment quantity by 1” is not.
- DELETE: request removal of the target resource. Repeating the request should leave the intended state—resource absent—unchanged, though the server may return a different response the second time.
Use the method to describe the action, and the URI to identify the resource. A route such as /orders/42 can be read with GET, replaced with PUT, or removed with DELETE, while the method communicates the intended operation.
Retry only when the operation is safe to repeat
Networks can fail after a server has applied a request but before the client receives the response. If the request used an idempotent method, the client can generally retry it without changing the intended result. A non-idempotent POST should not be retried blindly: the first request may already have created a payment or order.
For operations that use POST but need retry protection, APIs commonly define an idempotency key or another deduplication token. The server must store and enforce that key consistently; merely adding a request header without server-side behavior does not make an operation idempotent. Confirm the API's contract before retrying after a timeout.
Return a status code that says what happened
| Code | Meaning | Typical use |
|---|---|---|
| 200 OK | Request succeeded; a representation may be returned. | Successful read or update with a response body. |
| 201 Created | Request succeeded and created a resource. | Return the new resource, often with a Location header. |
| 202 Accepted | Accepted for processing, but not completed yet. | Background job; include a way to check its status. |
| 204 No Content | Request succeeded and there is no response content. | Successful deletion or update with no body. |
| 400 Bad Request | The request cannot be processed due to a client-side problem. | Malformed syntax or invalid framing. |
| 401 Unauthorized | Valid authentication credentials are missing or unacceptable. | Authentication is required or failed. |
| 403 Forbidden | The server understood but refuses the request. | Authenticated caller lacks permission. |
| 404 Not Found | No current representation was found, or the server will not disclose one. | Unknown resource identifier. |
| 409 Conflict | The request conflicts with the current resource state. | Duplicate or incompatible state transition. |
| 422 Unprocessable Content | The content type and syntax are understood, but its instructions cannot be processed. | Well-formed body with a domain validation error. |
Frameworks and API conventions can refine how these codes are used, so keep one consistent contract. Do not return 200 for every outcome: clients need to distinguish success, accepted-but-pending work, authentication failures, missing resources, and validation errors.
Common API design mistakes
- Putting a delete or purchase action behind GET, which can be triggered by automated retrieval.
- Assuming every request can be retried after a timeout. Check method semantics and the endpoint's documented contract.
- Calling PUT “create only” or “update only” without defining what happens when the target exists or is absent.
- Returning 201 without identifying the created resource when the client needs to find it.
- Returning 202 while implying the job is already complete.
- Using 401 and 403 interchangeably. 401 is about authentication; 403 is refusal despite understanding the request.
Practical checklist
- Choose the method based on the requested action, not on convenience.
- Keep safe methods free of requested state changes.
- Document whether an endpoint is idempotent and how clients may retry it.
- Use deduplication for non-idempotent operations that must survive client retries.
- Return a status code and response body that accurately describe the result and next step.
- Test duplicate requests, timeouts, and repeated deletes or updates against the API contract.
Clear HTTP semantics make APIs easier to operate under retries and failures. Start by defining what repeating the request is allowed to do, then choose a method and response that make that behavior visible to clients.
Further reading
Want a structured Java learning path?
Explore Jaipur Engineers course options to connect Java fundamentals, debugging, backend development and project practice in a guided learning plan.