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

# Troubleshooting

> What comes up, and the fix for each.

## `402 insufficient_credits`

The balance is zero. Add credit in the dashboard under **Billing**; keys stay valid
and requests succeed again as soon as it lands. The SDKs raise
`TokzInsufficientCreditsError` so you can route it apart from outages. See
[Billing](https://docs.tokz.si/billing.md#handling-402-in-an-agent).

## `400 unknown_model`

The name is neither a catalog model nor a ready fine tune in this key's organization. A key
from another organization gets this same answer, and so does a model that was deleted or has
not finished. `message` lists the catalog models.

## `400 invalid_request`

The body is malformed. `message` says what to fix: a `choice` with fewer than two
options, duplicate option ids, too many texts or questions. The limits are on the
[Decisions](https://docs.tokz.si/decisions.md#limits) page, and `GET /v1/decide/models` returns them live.

```ts theme={null}
import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });
const { limits } = await tokz.listDecisionModels();
console.log(limits);
```

## `429`

The per-key rate limit, 120 requests a minute. Batch texts into one request (up to 64)
to do more per call. `decide_org_busy` means your organization has 16 texts in progress on
hosted fine tunes: wait for the `Retry-After` seconds and send again.

## `502` or `503`

The model service did not answer (`decide_upstream_error`) or is saturated
(`decide_busy`). These are safe to retry after a short wait. The SDKs never retry for
you, because a retry after a timeout could bill twice.

When the response has `Retry-After`, wait that many seconds. The SDKs hand it to you as
`err.retryAfter` and `err.retry_after`.

## `413 input_too_large`

A fine tune with 32 or more labels cannot run a long text on our servers, because each label
needs memory. `message` gives the longest text that fits, and how much memory running it on
your machine would take. Shorten the text, or use [`decideLocal`](https://docs.tokz.si/fine-tune#run-it-on-your-machine).

## `503 fine_tune_off`

Fine Tune is not available right now. Your own model answers this while it is off, and you can
still delete a model or cancel a job in the dashboard.

## `decideLocal` or `decide_local` fails

`decide_local` has the same messages, with its own install line.

| Message | Fix |
| - | - |
| `decideLocal needs onnxruntime-node and tokenizers` | Run the install line in the message. In Python it is `pip install "tokz[local]"` |
| `needs onnxruntime-node 1.26.0` or `needs onnxruntime 1.26.0 or older` | Other versions change the scores, so install the version it names |
| `cannot run on {platform} {arch}` | `onnxruntime-node` has no build there, for example on Alpine or an Intel Mac. Use `decide` |
| `Could not download model` | The first call needs the network. After that it works offline |
| `failed its checksum` | Run the call again to download it fresh |
| `Cannot write the model cache` | Set `TOKZ_CACHE_DIR` to a writable folder |
| `Model "..." not found for this API key` | The name is wrong, the key is from another organization, or the model was deleted |

## Bills more than expected

Every request bills at least 256 tokens, so many tiny requests cost more than one
batched request. Send up to 64 texts per call. A question with more than 16 options
bills at 3×. A fine tune with more than 16 labels does too: at 77 labels a text bills about 15
times its tokens. Running it on [your machine](https://docs.tokz.si/fine-tune.md#run-it-on-your-machine) is free.


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