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".