Errors
What each error across LLM Gateway, billing, quotas, policies, secrets, environments and agents means, whether to retry, and what to do.
The errors you can meet across kosem's products, with what each means, whether to retry and what to do. kosem's HTTP API answers errors as RFC 9457 problem documents whose reason and domain tell failures apart: API conventions explains their shape and every code. The LLM Gateway's provider endpoints answer in their provider's format instead.
LLM Gateway
The gateway's endpoints answer errors as the provider whose API you called would, so its SDK raises them as usual. An error after a stream started arrives in the stream.
| Status | Error | What it means | Retry | What to do |
|---|---|---|---|---|
400 | invalid_request | Request asks for a feature unavailable through translation, such as store on a translated Responses call | No | Send the whole conversation, or omit the field |
401 | invalid_api_key | API key is missing, wrong, expired or deleted | No | Use a project service account key |
403 | A permission error | Caller can't call the project's models | No | Ask a project Owner for LLM Gateway User |
403 | policy_violated | An org or project policy disables LLM Gateway or project providers | No | Ask an Owner or Policy Admin |
404 | model_not_found | No model with that alias in the project, or it needs attention | No | Check the alias on LLM Gateway; fix attention notes |
429 | The provider's | Upstream provider rate limit for your account | Yes | Wait per Retry-After; provider SDKs retry automatically |
429 | rate_limit_exceeded / rate_limit_error | Project rate quota reached | Yes | Wait per Retry-After unless X-Should-Retry: false |
429 | insufficient_quota, with X-Should-Retry: false | Monthly allowance exhausted with no credits left, or usage/spend limit reached | No | Owner or Billing Admin adds credits or raises limit |
501 | An API error | count_tokens on a translated model | No | Estimate tokens client-side |
502 | connection_refused, with X-Should-Retry: false | Upstream provider refused your provider key | No | Owner or LLM Gateway Admin replaces the provider key |
502, 504 | provider_unavailable, timeout | Provider unreachable or timed out | Yes | Retry with backoff |
503 | rate_limits_unavailable | kosem couldn't count the request temporarily | Yes | Retry with backoff |
Every answer has the header Kosem-Request-Id, which the project's request log shows the request under.
The LLM Gateway's insufficient_quota is also what your organization's usage limit sends once this month's charges reach it, if it's set to stop: its message names the limit. An Owner or Billing Admin raises it in Billing, or it lifts as the month ends.
Secrets
domain is secrets.kosem.ai.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
ADOPTED_SECRET_READ_ONLY | failed_precondition | The secret is shared by the organization, whose versions are its own | No | Add the version to the organization's secret |
ALIAS_TAKEN | already_exists | Another secret of the same organization or project has that name | No | Enter another name |
SECRET_SHARED | failed_precondition | A project can't delete a secret its organization shares with it | No | An Owner stops sharing it with the project |
SECRET_ADOPTED | failed_precondition | Projects have the organization's secret | No | Stop sharing it with every project, then delete it |
NO_ENABLED_VERSION | failed_precondition | latest names the newest enabled version, and the secret has none | No | Add a version or enable an existing one |
VERSION_DISABLED | failed_precondition | The version is disabled | No | Enable the version or read another |
VERSION_DESTROYED | failed_precondition | The version was destroyed, and its value with it | No | Read another enabled version |
Connections
domain is connections.kosem.ai.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
PROVIDER_REFUSED | failed_precondition | Provider refused trust or settings; detail says why | No | Fix trust or permissions externally and verify again |
PROVIDER_UNAVAILABLE | unavailable | External provider was out of reach | Yes | Retry with backoff |
CREDENTIAL_REFUSED | failed_precondition | Scope exceeds ceiling, or connection needs attention / isn't shared | No | Narrow scope or fix connection |
CONNECTION_IN_USE | failed_precondition | Access profiles use the connection | No | Delete them first, or delete with force |
CONNECTION_CHANGED | aborted | Connection settings changed during verification | Yes | Read again and retry |
SERVICE_ACCOUNT_IN_USE | failed_precondition | Access profiles use this Google Cloud service account | No | Move or delete them first |
IAM_ROLE_IN_USE | failed_precondition | Access profiles assume this AWS IAM role | No | Move or delete them first |
INSTALLATION_TAKEN | already_exists | GitHub App installation is already connected elsewhere | No | Use another installation |
INSTALLATION_NOT_REACHED | permission_denied | Caller doesn't manage that GitHub installation | No | Ask a GitHub org owner to connect it |
GITHUB_STATE_INVALID | failed_precondition | GitHub setup state expired (30m) or belonged elsewhere | No | Start connecting GitHub again |
LLM Gateway's providers and models
domain is llmgateway.kosem.ai.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
PROVIDER_IN_USE | failed_precondition | Models use the provider | No | Delete them first, or delete with force |
PROVIDER_REFUSED | failed_precondition | Provider refused its key or settings; detail says why | No | Check and replace or fix settings |
PROVIDER_CHANGED | aborted | Provider changed while being updated or verified | Yes | Read again and retry |
PROVIDER_NOT_SUPPORTED | failed_precondition | Gateway doesn't serve models of this provider type | No | Select a supported provider type |
PROVIDER_QUOTA_EXHAUSTED | failed_precondition | Upstream provider account is out of credit or hit its limit | No | Add credit or raise limit at the provider |
PROVIDER_RATE_LIMITED | resource_exhausted | Upstream provider is rate limiting requests | Yes | Wait per retryAfter or retry with backoff |
PROVIDER_UNAVAILABLE | unavailable | Upstream provider unreachable or busy | Yes | Retry with backoff |
MODEL_ADOPTED | failed_precondition | Projects adopted this org model | No | Delete with force to remove project copies too |
ALREADY_ADOPTED | already_exists | Project already adopted this org model | No | Call it by the project's alias or rename it |
ALIAS_TAKEN | already_exists | Another model in this parent uses that alias | No | Choose another alias |
MODEL_NOT_FOUND | not_found | No model with that alias in the project, or unshared | No | Check LLM Gateway › Models |
SPEND_LIMIT_REACHED | resource_exhausted | Project or org reached its monthly spend limit (UTC) | No | Raise the spend limit or wait for next month |
CONTEXT_LENGTH_EXCEEDED | invalid_argument | Request exceeds the model's context window | No | Shorten input or pick a larger-context model |
CONTENT_FILTERED | invalid_argument | Provider safety filter rejected the input | No | Revise the input |
Environments
domain is environments.kosem.ai. Agents' operations give the image errors too, for an agent's image.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
IMAGE_PULL_DENIED | failed_precondition | The image's registry refused to let kosem pull it without signing in, as for a private image | No | Share a registry that covers it with the project, add one to the project, or request one |
REGISTRY_SIGN_IN_REFUSED | failed_precondition | The registry that covers the image refused kosem's sign-in | No | Check the registry's sign-in, and replace its token if it expired |
IMAGE_NOT_FOUND | failed_precondition | The registry has no such image | No | Check the image's name and tag |
IMAGE_TOO_LARGE | failed_precondition | The image is over 5 GB, compressed | No | Use a smaller image |
ENVIRONMENT_DELETING | failed_precondition | The environment is being deleted | No | Nothing: it can only finish |
REGISTRY_PREFIX_TAKEN | already_exists | The organization or project has a registry of that prefix | No | Change the registry that has it |
Agents
domain is agents.kosem.ai.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
CALL_NOT_OPEN | failed_precondition | The tool call isn't waiting for an answer | No | Read the agent's transcript to see open calls before answering |
MODEL_UNAVAILABLE | failed_precondition | The agent's config names a model not available in the project | No | Add the model to the project or select another model |
Billing
domain is billing.kosem.ai.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
CREDITS_EXHAUSTED | resource_exhausted | The organization used this month's allowance and has no credits left; metadata names sku | No | An Owner or Billing Admin buys credits in Billing |
FREE_ALLOWANCE_USED | resource_exhausted | The organization used this month's (UTC) free allowance; metadata names sku | No | Buy credits in Billing, or wait for the next calendar month |
USAGE_LIMIT_REACHED | resource_exhausted | This month's (UTC) charges reached the organization's usage limit; metadata names sku | No | An Owner or Billing Admin raises the usage limit in Billing › Overview |
ACCOUNT_SUSPENDED | resource_exhausted or failed_precondition | The billing account is suspended, such as after a payment dispute | No | Contact kosem support to resolve the suspension |
ALREADY_SUBSCRIBED | failed_precondition | The organization already has an active or pending subscription | No | Manage the existing subscription in Billing |
Policies and settings
domain is policies.kosem.ai (or settings.kosem.ai for settings ETAG_MISMATCH).
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
POLICY_VIOLATED | failed_precondition | An organization or project policy forbids what was asked. metadata names constraint, scope (organizations/… or projects/…) and value | No | Stay within the policy, or ask an Owner or Policy Admin to change it |
ETAG_MISMATCH | failed_precondition (412) | The policy or settings changed since you read them (If-Match didn't match the current ETag) | Yes | Read the policy or settings again, apply your change and retry with the new ETag |
Quotas
domain is quotas.kosem.ai.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
QUOTA_EXCEEDED | resource_exhausted | The organization or account reached a resource limit. metadata names quota_id, limit, subject and adjustment: REQUEST, kosem raises it on request; UPGRADE, a higher plan raises it; FIXED, it doesn't change | No | Delete unused resources; on Team or Enterprise, ask for more; on Hobby or Pro, upgrade |
RATE_LIMIT_EXCEEDED | resource_exhausted | A project reached a per-minute rate quota. metadata names quota_id, limit and subject; retryAfter says when to retry | Yes | Wait at least retryAfter seconds. Without retryAfter, the request exceeds the limit and can't fit |
PLAN_REQUIRED | failed_precondition | Requesting a quota increase takes Team or Enterprise | No | Upgrade to Pro or Team for higher limits |
Limits and quotas lists every quota.
Plans
domain is entitlements.kosem.ai.
| Reason | Code | What it means | Retry | What to do |
|---|---|---|---|---|
PLAN_REQUIRED | failed_precondition | The organization's plan doesn't include what was asked, such as custom providers on Hobby or audit logs and editable policies on Hobby or Pro. metadata names feature, adjustment and required_plan (PRO or TEAM) | No | Upgrade to the plan named in required_plan in Billing |