> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hostlinku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common errors

> Causes and fixes for the most common Hostlinku error codes.

Every error uses the same envelope: `{"error": {"code": "...", "message": "..."}}`. See the full list in [Errors](https://docs.hostlinku.com/en/errors.md).

## 401 UNAUTHORIZED

The API key is missing, incorrect, revoked, or expired. Use `Authorization: Bearer sk-...` or `x-api-key`, then check the key status in Console → **API Keys**.

## 402 PAYMENT\_REQUIRED

Two common causes:

* **Account balance** is too low for the estimated request cost.
* **API key credit limit** is reached (daily, weekly, monthly, or total).

Read the error message to tell them apart. Check balance and key limits in Console. Details: [Billing & Balance](https://docs.hostlinku.com/en/billing.md).

## 404 MODEL\_NOT\_FOUND

The model slug is not in the catalog. Copy the slug from `GET /v1/models` or the [Models](https://docs.hostlinku.com/en/models.md) page.

## 400 MODEL\_NOT\_IN\_SERVICE\_MODE

The model exists but is not available for the API key's Service Mode. Create a key with the right mode or pick another model.

## 422 VALIDATION\_FAILED

The request body failed validation: empty `messages`, wrong field type, or a missing required field. The response includes per-field details.

## 429 RATE\_LIMITED

The request limit was exceeded. Read `Retry-After` and `RateLimit-*`, then retry with exponential backoff. Rate-limited requests do not consume balance. Details: [Usage & Limits](https://docs.hostlinku.com/en/usage-and-limits.md).

## 503 MODEL\_UNAVAILABLE / UPSTREAM\_ERROR

The model is deprecated/unavailable, or the upstream has a temporary issue. Retry later for `UPSTREAM_ERROR`; for `MODEL_UNAVAILABLE`, check for a `replacement_slug`.

Debugging tip

Keep the `x-request-id` response header. It lets support match the request with Console logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.