SUQODocs
User GuideAPI ReferenceSDKs
TypeScript SDK v2.0.0. This version is frozen and no longer updated. Read the latest (2.1.0).

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.

Rate limiting is live as of 2.0.0 — on 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

Status: Planned. Idempotency keys are not yet supported by the backend — this section documents the intended header and behaviour now so it drops in cleanly once it is, rather than being bolted on later.

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

Status: Named, not built. The API doesn't send these headers, and no SDK code reads them.

Beyond Retry-After, names are already reserved for quota metadata, following the IETF RateLimit-* draft that GitHub and Cloudflare have converged on:

Response headerSDK field
RateLimit-LimitrateLimitLimit
RateLimit-RemainingrateLimitRemaining
RateLimit-ResetrateLimitReset

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.

On this page