A 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...
A spec used only to render docs cannot stop a malformed request from reaching your handlers. Runtime validation middleware uses the same OpenAPI document to check incoming requests and outgoing responses, returning consistent 400s with field-level errors. Here is how request and response...
A 429 with no Retry-After just makes clients guess, hammer harder, or give up. A usable rate-limit contract states the quota window, the remaining count, and exactly when to retry. Here is how to model 429, Retry-After, and the RateLimit headers in OpenAPI and verify the backoff with a mock.
Two clients PUT the same resource and the last write silently wins. The HTTP fix is conditional requests with ETag, If-Match, and a 412 that tells the client to re-fetch and retry. Here is the exact state table and the OpenAPI that makes codegen and AI agents handle conflicts correctly.
