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.	Per-plan concurrent connection cap reached at credential issuance (`POST /api/v1/credentials`). Plan-level API key limit reached.
`429 Too Many Requests`	Rate limited. Too many requests in a time window.	Login attempts exceeded the rate limit; Stripe Checkout session creation throttled.

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 API key, expired session cookie, revoked JWT credential, or unknown token prefix.
`403 Forbidden`	Credentials are valid but the principal lacks permission for this action.	Insufficient IAM permissions, scope not granted to API key, IP allowlist block, CSRF token missing, cross-tenant access denied.

Client Errors

Code	Meaning	When returned
`400 Bad Request`	Malformed request.	Invalid JSON, missing required fields, validation failures.
`404 Not Found`	Resource does not exist or does not belong to the caller’s tenant.	Tenant/project/key not found, or belongs to a different tenant.
`409 Conflict`	Duplicate resource.	Duplicate project names, duplicate CIDR in allowlist.
`422 Unprocessable Entity`	Semantically invalid request.	Invalid CIDR notation, plan limit exceeded on Free plan features.

Server Errors

Code	Meaning
`500 Internal Server Error`	Database failure, signing error, or unhandled internal error. Retryable.
`503 Service Unavailable`	Database connectivity lost. Returned by `GET /readyz` only.