# 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](/reference/api-conventions#errors) explains their shape and every `code`. The LLM Gateway's provider endpoints answer in their provider's format instead.

## LLM Gateway [#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](/reference/limits#your-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 [#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 [#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 [#llm-gateways-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 [#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 [#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 [#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 [#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 [#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](/reference/limits#raising-a-limit); 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](/reference/limits) lists every quota.

## Plans [#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** |

## Related [#related]

- [API conventions](/reference/api-conventions#errors)
- [Limits and quotas](/reference/limits)
