Skip to Content
kosemdocs
Reference

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.

StatusErrorWhat it meansRetryWhat to do
400invalid_requestRequest asks for a feature unavailable through translation, such as store on a translated Responses callNoSend the whole conversation, or omit the field
401invalid_api_keyAPI key is missing, wrong, expired or deletedNoUse a project service account key
403A permission errorCaller can't call the project's modelsNoAsk a project Owner for LLM Gateway User
403policy_violatedAn org or project policy disables LLM Gateway or project providersNoAsk an Owner or Policy Admin
404model_not_foundNo model with that alias in the project, or it needs attentionNoCheck the alias on LLM Gateway; fix attention notes
429The provider'sUpstream provider rate limit for your accountYesWait per Retry-After; provider SDKs retry automatically
429rate_limit_exceeded / rate_limit_errorProject rate quota reachedYesWait per Retry-After unless X-Should-Retry: false
429insufficient_quota, with X-Should-Retry: falseMonthly allowance exhausted with no credits left, or usage/spend limit reachedNoOwner or Billing Admin adds credits or raises limit
501An API errorcount_tokens on a translated modelNoEstimate tokens client-side
502connection_refused, with X-Should-Retry: falseUpstream provider refused your provider keyNoOwner or LLM Gateway Admin replaces the provider key
502, 504provider_unavailable, timeoutProvider unreachable or timed outYesRetry with backoff
503rate_limits_unavailablekosem couldn't count the request temporarilyYesRetry 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.

ReasonCodeWhat it meansRetryWhat to do
ADOPTED_SECRET_READ_ONLYfailed_preconditionThe secret is shared by the organization, whose versions are its ownNoAdd the version to the organization's secret
ALIAS_TAKENalready_existsAnother secret of the same organization or project has that nameNoEnter another name
SECRET_SHAREDfailed_preconditionA project can't delete a secret its organization shares with itNoAn Owner stops sharing it with the project
SECRET_ADOPTEDfailed_preconditionProjects have the organization's secretNoStop sharing it with every project, then delete it
NO_ENABLED_VERSIONfailed_preconditionlatest names the newest enabled version, and the secret has noneNoAdd a version or enable an existing one
VERSION_DISABLEDfailed_preconditionThe version is disabledNoEnable the version or read another
VERSION_DESTROYEDfailed_preconditionThe version was destroyed, and its value with itNoRead another enabled version

Connections

domain is connections.kosem.ai.

ReasonCodeWhat it meansRetryWhat to do
PROVIDER_REFUSEDfailed_preconditionProvider refused trust or settings; detail says whyNoFix trust or permissions externally and verify again
PROVIDER_UNAVAILABLEunavailableExternal provider was out of reachYesRetry with backoff
CREDENTIAL_REFUSEDfailed_preconditionScope exceeds ceiling, or connection needs attention / isn't sharedNoNarrow scope or fix connection
CONNECTION_IN_USEfailed_preconditionAccess profiles use the connectionNoDelete them first, or delete with force
CONNECTION_CHANGEDabortedConnection settings changed during verificationYesRead again and retry
SERVICE_ACCOUNT_IN_USEfailed_preconditionAccess profiles use this Google Cloud service accountNoMove or delete them first
IAM_ROLE_IN_USEfailed_preconditionAccess profiles assume this AWS IAM roleNoMove or delete them first
INSTALLATION_TAKENalready_existsGitHub App installation is already connected elsewhereNoUse another installation
INSTALLATION_NOT_REACHEDpermission_deniedCaller doesn't manage that GitHub installationNoAsk a GitHub org owner to connect it
GITHUB_STATE_INVALIDfailed_preconditionGitHub setup state expired (30m) or belonged elsewhereNoStart connecting GitHub again

LLM Gateway's providers and models

domain is llmgateway.kosem.ai.

ReasonCodeWhat it meansRetryWhat to do
PROVIDER_IN_USEfailed_preconditionModels use the providerNoDelete them first, or delete with force
PROVIDER_REFUSEDfailed_preconditionProvider refused its key or settings; detail says whyNoCheck and replace or fix settings
PROVIDER_CHANGEDabortedProvider changed while being updated or verifiedYesRead again and retry
PROVIDER_NOT_SUPPORTEDfailed_preconditionGateway doesn't serve models of this provider typeNoSelect a supported provider type
PROVIDER_QUOTA_EXHAUSTEDfailed_preconditionUpstream provider account is out of credit or hit its limitNoAdd credit or raise limit at the provider
PROVIDER_RATE_LIMITEDresource_exhaustedUpstream provider is rate limiting requestsYesWait per retryAfter or retry with backoff
PROVIDER_UNAVAILABLEunavailableUpstream provider unreachable or busyYesRetry with backoff
MODEL_ADOPTEDfailed_preconditionProjects adopted this org modelNoDelete with force to remove project copies too
ALREADY_ADOPTEDalready_existsProject already adopted this org modelNoCall it by the project's alias or rename it
ALIAS_TAKENalready_existsAnother model in this parent uses that aliasNoChoose another alias
MODEL_NOT_FOUNDnot_foundNo model with that alias in the project, or unsharedNoCheck LLM Gateway › Models
SPEND_LIMIT_REACHEDresource_exhaustedProject or org reached its monthly spend limit (UTC)NoRaise the spend limit or wait for next month
CONTEXT_LENGTH_EXCEEDEDinvalid_argumentRequest exceeds the model's context windowNoShorten input or pick a larger-context model
CONTENT_FILTEREDinvalid_argumentProvider safety filter rejected the inputNoRevise the input

Environments

domain is environments.kosem.ai. Agents' operations give the image errors too, for an agent's image.

ReasonCodeWhat it meansRetryWhat to do
IMAGE_PULL_DENIEDfailed_preconditionThe image's registry refused to let kosem pull it without signing in, as for a private imageNoShare a registry that covers it with the project, add one to the project, or request one
REGISTRY_SIGN_IN_REFUSEDfailed_preconditionThe registry that covers the image refused kosem's sign-inNoCheck the registry's sign-in, and replace its token if it expired
IMAGE_NOT_FOUNDfailed_preconditionThe registry has no such imageNoCheck the image's name and tag
IMAGE_TOO_LARGEfailed_preconditionThe image is over 5 GB, compressedNoUse a smaller image
ENVIRONMENT_DELETINGfailed_preconditionThe environment is being deletedNoNothing: it can only finish
REGISTRY_PREFIX_TAKENalready_existsThe organization or project has a registry of that prefixNoChange the registry that has it

Agents

domain is agents.kosem.ai.

ReasonCodeWhat it meansRetryWhat to do
CALL_NOT_OPENfailed_preconditionThe tool call isn't waiting for an answerNoRead the agent's transcript to see open calls before answering
MODEL_UNAVAILABLEfailed_preconditionThe agent's config names a model not available in the projectNoAdd the model to the project or select another model

Billing

domain is billing.kosem.ai.

ReasonCodeWhat it meansRetryWhat to do
CREDITS_EXHAUSTEDresource_exhaustedThe organization used this month's allowance and has no credits left; metadata names skuNoAn Owner or Billing Admin buys credits in Billing
FREE_ALLOWANCE_USEDresource_exhaustedThe organization used this month's (UTC) free allowance; metadata names skuNoBuy credits in Billing, or wait for the next calendar month
USAGE_LIMIT_REACHEDresource_exhaustedThis month's (UTC) charges reached the organization's usage limit; metadata names skuNoAn Owner or Billing Admin raises the usage limit in Billing › Overview
ACCOUNT_SUSPENDEDresource_exhausted or failed_preconditionThe billing account is suspended, such as after a payment disputeNoContact kosem support to resolve the suspension
ALREADY_SUBSCRIBEDfailed_preconditionThe organization already has an active or pending subscriptionNoManage the existing subscription in Billing

Policies and settings

domain is policies.kosem.ai (or settings.kosem.ai for settings ETAG_MISMATCH).

ReasonCodeWhat it meansRetryWhat to do
POLICY_VIOLATEDfailed_preconditionAn organization or project policy forbids what was asked. metadata names constraint, scope (organizations/… or projects/…) and valueNoStay within the policy, or ask an Owner or Policy Admin to change it
ETAG_MISMATCHfailed_precondition (412)The policy or settings changed since you read them (If-Match didn't match the current ETag)YesRead the policy or settings again, apply your change and retry with the new ETag

Quotas

domain is quotas.kosem.ai.

ReasonCodeWhat it meansRetryWhat to do
QUOTA_EXCEEDEDresource_exhaustedThe 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 changeNoDelete unused resources; on Team or Enterprise, ask for more; on Hobby or Pro, upgrade
RATE_LIMIT_EXCEEDEDresource_exhaustedA project reached a per-minute rate quota. metadata names quota_id, limit and subject; retryAfter says when to retryYesWait at least retryAfter seconds. Without retryAfter, the request exceeds the limit and can't fit
PLAN_REQUIREDfailed_preconditionRequesting a quota increase takes Team or EnterpriseNoUpgrade to Pro or Team for higher limits

Limits and quotas lists every quota.

Plans

domain is entitlements.kosem.ai.

ReasonCodeWhat it meansRetryWhat to do
PLAN_REQUIREDfailed_preconditionThe 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)NoUpgrade to the plan named in required_plan in Billing

On this page