> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Canonical reference for HTTP error codes returned by Qumo Deploy APIs.

# 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.                                               |

<Warning>
  **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.
</Warning>

## 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.              |