Document rate limits in OpenAPI so clients actually back off: 429, Retry-After, and rate-limit headers
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.