Error reference
Every error the Platform API can return, consolidated. Conventional HTTP codes — 5xx are retryable, 4xx are terminal except 429 and the 409 state codes.
The Platform API uses conventional HTTP status codes. Every error body has an error field and, where it adds detail, a reason.
- 5xx are server-side and retryable with backoff.
- 4xx are terminal — the request will not succeed unchanged — except:
- 429
rate_limited, which means retry later (see Rate limits). - the 409 state codes (
suspended,account_inactive), which mean retry on the right event — once the tenant is unsuspended or the account is activated.
- 429
All errors
| Status | error | reason(s) | Source / when |
|---|---|---|---|
| 400 | missing_fields | external_ref required, whu.email required, tenant_id or external_ref required, entitlements required, idempotency_key required | A required field is absent for the endpoint called |
| 400 | invalid_email | — | create: whu.email failed validation |
| 400 | invalid_amount | amount must be a positive finite number | topup: amount non-positive or non-finite |
| 401 | unauthorized | missing_bearer, invalid_key, account_missing, account_disabled | Authentication |
| 404 | tenant_not_found | — | No tenant matched the identifier under your account (including after terminate) |
| 404 | account_not_found | — | Defensive — your account row was not found |
| 405 | method_not_allowed | — | Any method other than POST |
| 409 | account_inactive | account status | create, sso: your account is not active (e.g. draft) |
| 409 | suspended | — | topup, sso: the tenant is suspended |
| 409 | tenant_not_active | — | topup: the tenant is not in an active state |
| 410 | terminated | — | The tenant has been terminated |
| 429 | rate_limited | per_key, per_ip | Rate limits |
| 500 | provision_failed | RPC message | create failed server-side |
| 500 | update_failed | RPC message | plan failed server-side |
| 500 | topup_failed | RPC message | topup failed server-side |
| 500 | suspend_failed | RPC message | suspend failed server-side |
| 500 | unsuspend_failed | RPC message | unsuspend failed server-side |
| 500 | terminate_failed | RPC message | terminate failed server-side |
| 500 | usage_read_failed | workspace_lookup_failed, credit_transactions_failed, cloud_usage_failed | usage failed server-side |
| 500 | internal_error | hash_failed, lookup_failed, account_lookup_failed | Authentication / sso failed server-side |
Treat 404 and 410 the same after terminate
Once a tenant is terminated its workspace row is deleted, so subsequent calls
return 404 tenant_not_found rather than 410 terminated. Both mean the
service is gone — do not retry either. See Idempotency.
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.
Request tracing & audit log
Pass your own request id to correlate logs, read how state-changing calls are audited, and why these server-to-server endpoints must never be called from a browser.