Skip to main content
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: 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "doc_url": "https://docs.orq.ai/errors/invalid_api_key"
  }
}

​
Quick reference

CodeHTTPCategory
authentication_required401Auth
invalid_api_key401Auth
expired_api_key401Auth
insufficient_scope403Auth
wrong_project403Auth
workspace_disabled403Auth
quota_exceeded402Quota
invalid_request_body400Validation
unsupported_engine400Validation
variant_not_resolved422Validation
model_configuration_missing422Validation
provider_credential_invalid422Validation
deployment_not_found404Not Found
integration_not_found404Not Found
prompt_snippet_not_found404Not Found
rate_limit_exceeded429Rate Limiting
provider_error502Provider
provider_timeout504Provider
provider_overloaded503Provider
internal_error500Server
not_implemented501Server
service_unavailable503Server
request_timeout408Server

​
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 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:
EntityDeveloperGrowthEnterprise
Deployments3UnlimitedUnlimited
Agents3UnlimitedUnlimited
Knowledge Bases + Memory Stores2UnlimitedUnlimited
Webhooks15Unlimited
Knowledge Bases and Memory Stores share a single combined limit. To increase limits, upgrade the plan.

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

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

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

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