Error Handling

Every error Kyma returns has a stable error.code, a category in error.type, error.retryable, and a request_id. The full list, with what each code means and what to do, is on Errors. This page shows how to act on them.

Branch on `error.code`

{
  "error": {
    "message": "Auth required",
    "type": "authentication_error",
    "code": "missing_api_key",
    "param": null,
    "retryable": false,
    "request_id": "req_609c801a70854f05bf145b4e190c22de",
    "doc_url": "https://docs.kymaapi.com/api-reference/errors#missing_api_key"
  }
}

error.code is always a string, on every status. Read it, not error.message: the message is written for people and can change. On /v1/messages the same object sits in Anthropic’s envelope ("type": "error" on top), so Anthropic SDKs work unchanged.

Status	Most common codes	What to do
`400`	`invalid_json`, `missing_parameter`, `invalid_parameter`, `wrong_endpoint`, `unsupported_content`, `request_rejected`	Fix the request as `error.message` says. `wrong_endpoint` names the endpoint to call instead
`401`	`missing_api_key`, `invalid_api_key`	Send `Authorization: Bearer <key>` with a key from kymaapi.com/keys
`402`	`model_requires_paid`, `insufficient_credits`	Add credits, pick a free-tier model, or lower `max_tokens`. See below
`403`	`route_refused`	The model refused this content. Try a model from `error.suggested_models`; retrying unchanged fails the same way
`404`	`model_not_found`	Use an id from `did_you_mean` or `GET /v1/models`
`413`	`request_too_large`	Split the request or downscale images
`429`	`rate_limit_exceeded`	Wait `Retry-After` seconds. See Rate Limits
`502`	`upstream_invalid_response`	Retry
`503`	`provider_unavailable`, `model_unavailable`	Retry after `Retry-After`, or use another model

A 200 with an empty billed body is a bug, not a valid “no result”. Out of credits is 402, never 200.

Retry only what can succeed

error.retryable, and the x-should-retry header, say whether the same request can succeed if sent again. The official OpenAI and Anthropic SDKs read x-should-retry and retry twice by default, so they already skip a 402 or a 400. If you retry yourself: honor Retry-After, back off exponentially with jitter, and never retry a non-retryable error unchanged.

The two `402` codes

A 402 is always about money or free-tier access, never about your payload. error.type is billing_error and error.code names the rule:

Code	Means	What to do
`model_requires_paid`	Your account has never added credits and this model is not in the free tier	Add credits, or use a model with `free_tier: true` in `GET /v1/models`
`insufficient_credits`	Your balance does not cover this request	Add credits, or lower `max_tokens`. `need_usd` and `have_usd` say by how much

On the OpenAI-compatible endpoints the body is:

{
  "need_usd": 0.012562,
  "have_usd": 0.0004,
  "topup": "https://api.kymaapi.com/v1/topup",
  "balance": 0.0004,
  "required": 0.012562,
  "topup_url": "https://kymaapi.com/billing",
  "error": {
    "message": "This request needs about $0.01 of credit; you have $0.0004. Top up at https://kymaapi.com/billing or lower max_tokens.",
    "type": "billing_error",
    "code": "insufficient_credits",
    "param": null,
    "retryable": false,
    "request_id": "req_3714ef7e95334c67a11baaec598159e6",
    "doc_url": "https://docs.kymaapi.com/api-reference/errors#insufficient_credits"
  },
  "details": {
    "balance": 0.0004,
    "required": 0.012562,
    "topup_url": "https://kymaapi.com/billing",
    "hint": "Top up at least $0.02 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one",
    "endpoint_id": "deepseek-v3"
  }
}

On /v1/messages the same fields arrive in Anthropic’s envelope: "type": "error" and request_id at the top level, and error.type is billing_error, Anthropic’s own type for a 402:

{
  "type": "error",
  "need_usd": 0.012562,
  "have_usd": 0.0004,
  "topup": "https://api.kymaapi.com/v1/topup",
  "balance": 0.0004,
  "required": 0.012562,
  "topup_url": "https://kymaapi.com/billing",
  "error": {
    "message": "This request needs about $0.01 of credit; you have $0.0004. Top up at https://kymaapi.com/billing or lower max_tokens.",
    "type": "billing_error",
    "code": "insufficient_credits",
    "param": null,
    "retryable": false,
    "doc_url": "https://docs.kymaapi.com/api-reference/errors#insufficient_credits",
    "request_id": "req_…"
  },
  "details": {
    "balance": 0.0004,
    "required": 0.012562,
    "topup_url": "https://kymaapi.com/billing",
    "hint": "Top up at least $0.02 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one",
    "endpoint_id": "deepseek-v3"
  },
  "request_id": "req_…"
}

On an image or audio model, model_requires_paid names the free-tier alternatives by id:

{
  "topup": "https://api.kymaapi.com/v1/topup",
  "balance": 0.5,
  "required": 0,
  "topup_url": "https://kymaapi.com/billing",
  "error": {
    "message": "gpt-image-2 is not in the free tier; add credits to use it. Free-tier media: gemini-3.5-transcribe, gpt-4o-mini-transcribe-2025-12-15, gpt-transcribe, minimax-image-01, whisper-v3-turbo.",
    "type": "billing_error",
    "code": "model_requires_paid",
    "param": null,
    "retryable": false,
    "request_id": "req_…",
    "doc_url": "https://docs.kymaapi.com/api-reference/errors#model_requires_paid"
  },
  "details": {
    "balance": 0.5,
    "required": 0,
    "topup_url": "https://kymaapi.com/billing",
    "hint": "Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one",
    "endpoint_id": "gpt-image-2"
  }
}

topup_url is the billing page a person opens. topup is the endpoint an agent with a wallet can pay on its own; it is a hint in the body, never a payment challenge. required is 0 on model_requires_paid on purpose. The $0.50 signup credit spends on the free tier and nothing else, so no top-up amount makes a paid model callable on it; quoting a figure there would send you to buy exactly enough credit to be refused again.

Rate limits

Rate limits are tier-based and counted per minute: RPM and TPM on text endpoints, concurrent jobs on media. Your tier’s numbers are live at GET /v1/limits/tiers, and Rate Limits explains each one. To see your tier and this minute’s usage:

curl https://api.kymaapi.com/v1/auth/limits \
  -H "Authorization: Bearer $KYMA_API_KEY"

The response includes tier, rpm_limit, tpm_limit, this minute’s rpm_used / rpm_remaining and tpm_used / tpm_remaining, and the full tier table. Checking it does not use up a request.

Python error handling

from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kymaapi.com/v1", api_key="YOUR_KEY")

try:
    response = client.chat.completions.create(
        model="qwen-3.6-plus",
        messages=[{"role": "user", "content": "Hello"}],
    )
except APIStatusError as e:
    if e.code in ("model_requires_paid", "insufficient_credits"):
        print("Add credits:", e.response.json().get("topup_url"))
    elif e.code == "rate_limit_exceeded":
        print("Slow down; retry after", e.response.headers.get("retry-after"), "s")
    else:
        # Quote this when you contact support.
        print(e.status_code, e.code, e.request_id)

Retry with a fallback model

When a model is unavailable (provider_unavailable, model_unavailable) or refuses the content (route_refused), another model may answer:

models = ["qwen-3.6-plus", "qwen-3-32b", "llama-3.3-70b"]

for model in models:
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": "Hello"}],
        )
        print(f"Success with {model}")
        break
    except APIStatusError as e:
        if e.code not in ("provider_unavailable", "model_unavailable", "route_refused"):
            raise

Guides

Use Cases

Integrations

Branch on `error.code`

Retry only what can succeed

The two `402` codes

Rate limits

Python error handling

Retry with a fallback model

​Branch on error.code

​Retry only what can succeed

​The two 402 codes

​Rate limits

​Python error handling

​Retry with a fallback model

Branch on `error.code`

Retry only what can succeed

The two `402` codes

Rate limits

Python error handling

Retry with a fallback model