Not yet implemented
Idempotency keys and rate-limit quota metadata — the intended behaviour, ahead of the feature.
Behaviours the SDK is built forward-ready for, which the backend doesn't support yet. They are documented here so the shape is settled ahead of the feature rather than bolted on after it, and so nothing on this page reads as if it already works.
checkoutSessions.create() only, 20 sessions a minute per account. How to handle it is in Handle errors → Rate limits. Only the quota metadata below is still unbuilt.Idempotency keys
Current behaviour
Write operations (create, update, replace, delete, cancel, updateBillingCycle, resume, renew, testDelivery) are not retried automatically by the SDK. The API does not yet support idempotency keys, so a retried write could double-act (e.g. open a second checkout session). This is a deliberate, single switch in the SDK's retry layer.
Read operations (list, retrieve, retrieveSecret) are unaffected: they're naturally idempotent and already retried on NetworkError, 429, and 5xx — see Errors.
Intended header
Once supported, write operations will accept an X-Idempotency-Key header. Sending the same key on a repeated write is intended to let the API deduplicate the request instead of performing the action twice.
Intended SDK behaviour
- The SDK will auto-generate a UUID idempotency key for each write call if the caller doesn't supply one.
- An override parameter will let callers pass their own key, e.g. to correlate a retry across separate calls.
- Once the header is honoured by the backend, writes will flip to retryable in the SDK's retry layer.
Why this isn't built yet
Idempotency support is blocked on the backend: the API must dedup requests on the X-Idempotency-Key value before the SDK can safely retry writes. Until the backend honours the header, writes stay non-retryable, and this section stays a description of intended behaviour rather than a reference for a shipped feature.
Rate-limit quota metadata
Beyond Retry-After, names are already reserved for quota metadata, following the IETF RateLimit-* draft that GitHub and Cloudflare have converged on:
| Response header | SDK field |
|---|---|
RateLimit-Limit | rateLimitLimit |
RateLimit-Remaining | rateLimitRemaining |
RateLimit-Reset | rateLimitReset |
They're listed here only so the names are settled ahead of time. Where exactly they'll surface (on every response, only on RateLimitError, or something else) is still open — this page will be updated with the real shape once that's decided and the headers actually start arriving.