Versioning, idempotency, and rate limits
Safe retries, clear rate-limit headers, and non-breaking version sunsets.
1. Idempotency-Key on POST mutations (ADP-012)
Clients pass a UUIDv4/v7 in Idempotency-Key. The server caches the response keyed by (tenant, method, path, key) and payload hash for 24h+, replaying the original 201 Created on network retries and returning 409 Conflict if the payload differs.
POST /v1/orders HTTP/1.1 Idempotency-Key: 019334b2-7d3a-7b8e-91c2-4a8e2e6f1100
2. IETF RateLimit headers and 429 backoff (ADP-013)
Return 429 Too Many Requests with Retry-After (seconds) and standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.
HTTP/1.1 429 Too Many Requests Content-Type: application/problem+json Retry-After: 15 RateLimit-Limit: 120 RateLimit-Remaining: 0 RateLimit-Reset: 15
3. Explicit versioning and RFC 8594 Sunset headers (ADP-004, ADP-018)
Keep minor releases additive (ADP-027). When retiring a major version, expose Deprecation and Sunset headers plus Link: <...>; rel="successor-version".