502 Bad Gateway vs 504: How to Tell Them Apart
Same gateway layer, two different failures, and two different fixes.
Read articleTopic
Same gateway layer, two different failures, and two different fixes.
Read articleOne green POST does not prove an endpoint is idempotent.
Read articleA practical way to separate request format errors from response negotiation problems, with cURL examples and a four-case regression checklist.
Read articleA network timeout never tells the client whether the charge happened. Retrying a plain POST double-creates; an Idempotency-Key header turns the retry into a replay. Here is the header contract, the in-flight 409 versus the stored response, key lifetime and scope, and the OpenAPI that makes SDKs...
Read articleLooping 500 POSTs from the client is slow and fails halfway with no way to recover. A bulk endpoint accepts an ordered batch and reports each item independently, including partial success with 207 Multi-Status. Here is the request envelope, per-item status and error arrays, idempotency, and the...
Read articleHolding an HTTP connection open for a three-minute export times out and ties up workers. Return 202 Accepted with a Location to a job resource, model the job state machine, and let clients poll or subscribe to a webhook. Here is the full lifecycle with progress and cancellation, and the OpenAPI...
Read articleAPIs return more than JSON: CSV exports, PDF invoices, ZIP archives, resized images, and generated audio. Model them with the right media type and string/binary schema, document Content-Disposition and Range, and distinguish inline from attachment. Here is how to describe downloads, conditional...
Read articleDeleting an endpoint is not a deprecation policy, and announcing it once in a changelog does not reach the integrations that actually call it. RFC 8594 gives you the Deprecation and Sunset response headers, Link rel=successor-version points at the replacement, and OpenAPI marks operations...
Read articlePATCH is not PUT with fewer fields; the media type defines its semantics. JSON Merge Patch treats null as delete and replaces arrays; JSON Patch sends atomic operations and pairs with optimistic concurrency. Here is when to use each and the OpenAPI for all three.
Read article