Error Code Reference
This page is the canonical reference for HTTP error codes returned by the Qumo Deploy API.Quota and Entitlement Errors
| Code | Meaning | When returned |
|---|---|---|
402 Payment Required | Plan entitlement exceeded. The request cannot proceed until the plan is upgraded. | Creating a prod project (POST /v1/projects) on a plan without the managed relay network (Free); create a dev project instead. Adding a domain (POST /v1/organizations/{id}/domains) or verifying a pending one (POST /v1/organizations/{id}/domains/{domainID}/verify) when the organization’s plan has no SSO (Free; SSO is on Pay as you go and Enterprise). Domains verified before a downgrade stay claimed; re-verifying (restoring) one and releasing one are never refused. |
429 Too Many Requests | Rate limited. Too many requests in a time window. | Login attempts or invalid TOTP codes exceeded the rate limit; Stripe Checkout or billing portal session creation throttled; relay discovery (GET /v1/relays), demo sessions or the contact form called too often. |
402 vs 429: These codes are not interchangeable.
402 signals a billing entitlement/upgrade is required. 429 signals transient rate limiting that recovers after exponential backoff.Authentication and Authorization Errors
| Code | Meaning | When returned |
|---|---|---|
401 Unauthorized | Missing or invalid credentials. | No credentials; a session cookie sent to the API host, which takes Bearer tokens only (see Authentication); an expired session; or an invalid, expired or revoked token. |
403 Forbidden | Credentials are valid but the principal lacks permission for this action. | Insufficient IAM permissions, scope not granted to the token, IP allowlist block, CSRF token missing, cross-organization access denied; adding a domain, or verifying a pending one, in an organization Qumo has suspended (organization is suspended), whatever its plan. |
Client Errors
| Code | Meaning | When returned |
|---|---|---|
400 Bad Request | Malformed request. | Invalid JSON, missing required fields, validation failures; an organization-scoped request that names no organization (organization_id is required), including GET /v1/projects from anyone but a platform admin. |
404 Not Found | Resource does not exist or does not belong to the caller’s organization. | Organization/project/key not found, or belongs to a different organization; a payment method ID that is not one of the organization’s saved cards (payment method not found). |
409 Conflict | Duplicate resource, or a conflicting state. | A second dev project in an organization; a signing key that is already registered, or a sixth active signing key in a project; a duplicate CIDR in an IP allowlist; a checkout for an organization that already has a live subscription; cancelling a subscription the organization does not have; adding a card before subscribing, or removing the only card a live subscription is charged to; an Identity token minted while the Identity was being granted a new role (mint again); removing an organization’s last Organization Admin, or deleting the account of an organization’s only Organization Admin. |
422 Unprocessable Entity | Semantically invalid request. | Invalid CIDR notation or missing label in an IP allowlist entry; an identity already at its IP allowlist entry limit; a fourth organization of your own (POST /v1/auth/organizations: you can own three); granting a role directly to a user who holds no role in the organization, or to a user id that names nobody (invite them instead). |
Server Errors
| Code | Meaning |
|---|---|
500 Internal Server Error | Database failure or unhandled internal error. Retryable. |
503 Service Unavailable | Database connectivity lost. Returned by GET /readyz only. |