Idempotency
How each endpoint behaves on retry — which carry an idempotency key, which are idempotent by state, and how to treat a terminated tenant.
Network calls fail and get retried. Every Platform API endpoint is designed so that a retry is safe, but the mechanism differs by endpoint. There are three patterns:
- Keyed. A retry is recognized by an explicit key and returns the original result.
createkeys on(account, external_ref);topupkeys on anidempotency_keyyou supply, scoped per tenant. - By state. The endpoint reads the tenant's current status and short-circuits if the work is already done —
suspend,unsuspend, andterminatereturnalready: true. - Naturally safe.
planoverwrites, so re-sending is harmless;ssomints a fresh token each time;usageis a pure read.
Per-endpoint behavior
| Endpoint | Idempotency key | On retry |
|---|---|---|
create | (account, external_ref) | Same tenant_id / dashboard_url; entitlements not overwritten |
plan | none | Overwrites entitlements; safe to re-send |
topup | idempotency_key (per tenant) | No-op; returns current balances |
sso | none | Fresh token each call |
suspend | by state | Already-suspended → already: true |
unsuspend | by state | Already-active → already: true |
terminate | by state | Already-terminated or gone → already: true |
usage | n/a | Pure read |
The post-terminate asymmetry
Entitlements
The per-tenant budget caps you set with create and plan. A JSONB object of known knobs — invalid keys and values are dropped silently, never rejected.
Rate limits
Per-key and per-IP minute buckets on every endpoint, the 429 response shape, and how a host should back off. SSO has a much higher budget.