> ## 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 every Orq.ai API error code with HTTP status, cause, and fix, covering auth, validation, rate limit, and provider errors.

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": "/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 |
| [guardrail\_not\_found](#guardrail_not_found) | 422 | Validation |
| [guardrail\_execution\_failed](#guardrail_execution_failed) | 502 | Server |
| [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](/ai-gateway/using-the-router) 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**.

***

### guardrail\_not\_found

**HTTP status:** 422

**When this occurs:** The **Deployment** or **Agent** still references a guardrail **Evaluator** that has since been deleted, so the guardrail cannot run. The error `details` include the `evaluator_id` that could not be resolved. Requests fail closed: no response is returned while an unresolvable guardrail is configured.

**How to fix it:** Open the affected **Deployment** or **Agent** settings. The deleted guardrail is listed as a missing entry in the Guardrails section. Remove it, or point the configuration at an existing **Evaluator**, then save.

***

### guardrail\_execution\_failed

**HTTP status:** 502

**When this occurs:** A configured guardrail could not be evaluated, for example because the evaluator runtime returned an error. Guardrails fail closed, so the request is rejected rather than allowed through unchecked. The error `details` include the `evaluator_id` and, when available, the `reason` reported by the evaluator runtime.

**How to fix it:** Inspect the evaluator span in **Traces** for the underlying failure. Fix the evaluator definition if the `reason` points at its configuration or code. Retry the request if the failure is transient, and contact [support@orq.ai](mailto:support@orq.ai) if it persists.

***

## 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://uptime.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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.