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

# API Error Codes

> Reference for all Orq.ai API error codes: HTTP status, cause, and resolution.

Every error response from the **Orq.ai** API includes an `error` object with a `code`, `message`, and `doc_url` field. Use the `code` to identify the exact failure and follow the resolution steps below.

**Error response shape:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "doc_url": "https://docs.orq.ai/errors/invalid_api_key"
  }
}
```

## Quick reference

| Code                                                          | HTTP | Category      |
| ------------------------------------------------------------- | ---- | ------------- |
| [authentication\_required](#authentication_required)          | 401  | Auth          |
| [invalid\_api\_key](#invalid_api_key)                         | 401  | Auth          |
| [expired\_api\_key](#expired_api_key)                         | 401  | Auth          |
| [insufficient\_scope](#insufficient_scope)                    | 403  | Auth          |
| [wrong\_project](#wrong_project)                              | 403  | Auth          |
| [workspace\_disabled](#workspace_disabled)                    | 403  | Auth          |
| [quota\_exceeded](#quota_exceeded)                            | 402  | Quota         |
| [invalid\_request\_body](#invalid_request_body)               | 400  | Validation    |
| [unsupported\_engine](#unsupported_engine)                    | 400  | Validation    |
| [variant\_not\_resolved](#variant_not_resolved)               | 422  | Validation    |
| [model\_configuration\_missing](#model_configuration_missing) | 422  | Validation    |
| [provider\_credential\_invalid](#provider_credential_invalid) | 422  | Validation    |
| [deployment\_not\_found](#deployment_not_found)               | 404  | Not Found     |
| [integration\_not\_found](#integration_not_found)             | 404  | Not Found     |
| [prompt\_snippet\_not\_found](#prompt_snippet_not_found)      | 404  | Not Found     |
| [rate\_limit\_exceeded](#rate_limit_exceeded)                 | 429  | Rate Limiting |
| [provider\_error](#provider_error)                            | 502  | Provider      |
| [provider\_timeout](#provider_timeout)                        | 504  | Provider      |
| [provider\_overloaded](#provider_overloaded)                  | 503  | Provider      |
| [internal\_error](#internal_error)                            | 500  | Server        |
| [not\_implemented](#not_implemented)                          | 501  | Server        |
| [service\_unavailable](#service_unavailable)                  | 503  | Server        |
| [request\_timeout](#request_timeout)                          | 408  | Server        |

***

## Authentication errors

### authentication\_required

**HTTP status:** 401

**When this occurs:** The request did not include a valid authentication header.

**How to fix it:** Include a valid **Orq.ai** API key in every request using the `Authorization` header:

```
Authorization: Bearer sk-orq-...
```

***

### invalid\_api\_key

**HTTP status:** 401

**When this occurs:** The API key supplied in the `Authorization` header is invalid.

**How to fix it:** Verify the key is copied correctly with no leading or trailing whitespace.

***

### expired\_api\_key

**HTTP status:** 401

**When this occurs:** The API key has passed its expiration date. The error `details` include `expired_at` (ISO timestamp).

**How to fix it:** Create a new API key and update it wherever it is used.

***

### insufficient\_scope

**HTTP status:** 403

**When this occurs:** The API key does not have the permission required for the requested operation. The error `details` include the `required` permission and the key's `scope` (`PUBLIC`, `WORKSPACE`, or `PROJECT`).

**How to fix it:** Use a key with broader permissions, or create a new key with the required permission level.

***

### wrong\_project

**HTTP status:** 403

**When this occurs:** The API key is scoped to a specific project, but the resource being accessed belongs to a different project. The error `details` include `key_project_id` and `resource_project_id`.

**How to fix it:** Use an API key scoped to the correct project.

***

### workspace\_disabled

**HTTP status:** 403

**When this occurs:** The workspace associated with the API key has been disabled. The error `details` may include a `reason`.

**How to fix it:** Contact [support@orq.ai](mailto:support@orq.ai) to investigate the workspace status.

***

## Quota

### quota\_exceeded

**HTTP status:** 402

**When this occurs:** The workspace has reached the limit for a resource on its current plan. The error `details` include `usage` (current count) and `limit` (plan maximum).

**How to fix it:** Delete unused resources to free up quota, or upgrade the plan.

**Plan limits:**

| Entity                          | Developer | Growth    | Enterprise |
| ------------------------------- | --------- | --------- | ---------- |
| Deployments                     | 3         | Unlimited | Unlimited  |
| Agents                          | 3         | Unlimited | Unlimited  |
| Knowledge Bases + Memory Stores | 2         | Unlimited | Unlimited  |
| Webhooks                        | 1         | 5         | Unlimited  |

Knowledge Bases and Memory Stores share a single combined limit.

To increase limits, [upgrade the plan](https://orq.ai/pricing).

***

## Validation errors

### invalid\_request\_body

**HTTP status:** 400

**When this occurs:** The request body failed schema validation. The error `details` include an `issues` array describing each validation failure.

**How to fix it:** Inspect the `issues` array in the error response to identify the fields that failed validation. Correct the request body to match the expected schema.

***

### unsupported\_engine

**HTTP status:** 400

**When this occurs:** The `model` value in the request references an engine that is not supported. The error `details` include the `engine` that was requested and a `supported` array of valid engines.

**How to fix it:** Use one of the model identifiers from the `supported` list, or check the [Models](/docs/model-garden/overview) page for available options.

***

### variant\_not\_resolved

**HTTP status:** 422

**When this occurs:** The deployment has multiple variants configured, but none of them matched the `context` supplied in the request. The error `details` include `context_keys` that were evaluated.

**How to fix it:** Ensure the `context` object in the request contains the keys the deployment's variant rules expect.

***

### model\_configuration\_missing

**HTTP status:** 422

**When this occurs:** The model assigned to the deployment could not be loaded. The error `details` include `model_db_id`.

**How to fix it:** Verify the model assigned to the deployment is still available. If the issue persists, contact [support@orq.ai](mailto:support@orq.ai).

***

### provider\_credential\_invalid

**HTTP status:** 422

**When this occurs:** The provider credential stored for the integration could not be decrypted or is malformed. The error `details` include the `provider` name and the `field` that failed.

**How to fix it:** Re-enter the credential for the affected provider in **Integrations**.

***

## Not found

### deployment\_not\_found

**HTTP status:** 404

**When this occurs:** No deployment exists with the `key` supplied in the request. The error `details` include the `key` that was looked up.

**How to fix it:** Verify the deployment key against the list in **AI Studio > Deployments**. Keys are case-sensitive.

***

### integration\_not\_found

**HTTP status:** 404

**When this occurs:** The integration identifier referenced in the request does not exist in the workspace. The error `details` include the `identifier`.

**How to fix it:** Check **Integrations** to confirm the integration exists. Ensure the identifier is spelled correctly.

***

### prompt\_snippet\_not\_found

**HTTP status:** 404

**When this occurs:** A prompt template references a snippet with a `key` that does not exist. The error `details` include the `key` that was looked up.

**How to fix it:** Create the missing snippet or update the prompt template to reference an existing snippet key.

***

## Rate limiting

### rate\_limit\_exceeded

**HTTP status:** 429

**When this occurs:** Requests are being sent faster than the workspace's allowed rate. The error `details` include `retry_after_seconds` (how long to wait before retrying) and optionally `limit` (the rate limit threshold).

**How to fix it:** Wait at least `retry_after_seconds` before retrying. Implement exponential backoff in the application. To request a limit increase, contact [support@orq.ai](mailto:support@orq.ai).

***

## Provider errors

### provider\_error

**HTTP status:** 502

**When this occurs:** The upstream AI provider returned an error response. The error `details` include the `provider` name, the `provider_status` HTTP code when available, and a `raw` error string when available.

**How to fix it:** Check the provider's status page for active incidents. Retry the request after a short delay.

***

### provider\_timeout

**HTTP status:** 504

**When this occurs:** The upstream provider did not respond within the allowed time window. The error `details` include the `provider` name and `timeout_ms` (the timeout that was exceeded).

**How to fix it:** Retry the request. For consistently slow responses, consider reducing prompt or context length or switching to a faster model.

***

### provider\_overloaded

**HTTP status:** 503

**When this occurs:** The upstream provider is temporarily overloaded and rejected the request. The error `details` include the `provider` name.

**How to fix it:** Retry with exponential backoff.

***

## Server errors

### internal\_error

**HTTP status:** 500

**When this occurs:** An unexpected error occurred inside **Orq.ai**. This is not caused by the request itself.

**How to fix it:** Retry the request. If the error persists, contact [support@orq.ai](mailto:support@orq.ai).

***

### not\_implemented

**HTTP status:** 501

**When this occurs:** The requested feature is not yet implemented. The error `details` include the `feature` name.

**How to fix it:** Contact [support@orq.ai](mailto:support@orq.ai) for more information.

***

### service\_unavailable

**HTTP status:** 503

**When this occurs:** A required internal dependency (database, cache, etc.) is temporarily unavailable. The error `details` may include the `dependency` name.

**How to fix it:** Retry the request after a short delay. Check the [Orq.ai status page](https://status.orq.ai) for active incidents.

***

### request\_timeout

**HTTP status:** 408

**When this occurs:** The request took longer than the server's maximum allowed processing time. The error `details` include `timeout_ms`.

**How to fix it:** Reduce the complexity of the request: shorter prompts, fewer context tokens, or a smaller `max_tokens` value.