# Errors

> The error envelope, the stable codes, and what to do about each.

Section: Developers. Web page: https://docs.katara.com/developers/errors/

Errors use the OpenAI envelope:

```json
{ "error": { "message": "…", "type": "insufficient_quota", "code": "insufficient_quota", "param": null } }
```

Branch on `code`. The `message` is for people and may change. Every response, success or error, has an `x-katara-request-id` header; include it when you write to support.

| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 400 | `invalid_request` | The body is malformed. | Fix the request. |
| 400 | `model_requires_usdc` | The key pays with account credits, and this model is served only for USDC. | Name another model, or use a key that pays with USDC. |
| 400 | `max_tokens_too_small` | The model reasons before it answers and the request's `max_tokens` leaves it no room to finish; nothing was sent to the model. The message names the floor, and `/v1/models` lists it as `min_output_tokens`. | Raise `max_tokens` or leave it unset. |
| 400 | `feature_not_supported` | The model does not support what the request asks for: tools, structured output, reasoning, a `tool_choice` outside its contract, or a parameter it does not act on (`param` names the field). A parameter left at its default is accepted and dropped. | Check `capabilities`, `tool_contract` and `supported_params` on `/v1/models`. |
| 401 | `invalid_api_key` | Missing or unknown key. Under `https://api.katara.com/test`, also a model call with no key. | Create a key in the portal. |
| 402 | `insufficient_credits` | The key pays with account credits, and the available credits cannot cover the request's maximum cost. | Add credits in **Billing** in the portal, or lower `max_tokens`. |
| 403 | `account_suspended` | The account behind the key is suspended. | Contact support. |
| 403 | `billing_suspended` | Credit billing is paused for the account. | Contact support. |
| 403 | `wrong_environment` | A Live key was sent to the Test network's address under `https://api.katara.com/test`. | Send it to `https://api.katara.com/v1`: the key decides the network. |
| 404 | `model_not_found` | Unknown model id. | Use an id from `/v1/models`. |
| 429 | `insufficient_quota` | The key pays with USDC, and its spendable balance is below the request's maximum cost. | Add USDC, raise the budget cap, or lower `max_tokens`. Honour `Retry-After`. |
| 502 | `provider_output_invalid` | Every provider tried answered with something Katara refused to deliver: a reply with no text and no tool call, a malformed tool call, tool syntax left in the text, a runtime fault, a reply stuck repeating itself, or a stop the runtime did not mean. Managed models are held to the same rule. Nothing was charged. | Retry after `Retry-After`. |
| 502 | `provider_rejected_request` | Every provider tried refused the request body itself: a conversation history its runtime will not render, or a field it cannot take. Nothing was charged and a retry of the same request will fail the same way. | Check the history and parameters, then send a corrected request. |
| 502 | `test_network_unavailable` | A Test key's request did not reach the Test network. Nothing was charged. | Retry after `Retry-After`. |
| 503 | `no_capacity` | No provider can serve the named model right now; for `katara/cortex@1`, no candidate could. A named model is never substituted. Test has no managed fallback, so a Test request sees this whenever no Test provider is free. | Retry after `Retry-After`, or ask `katara/cortex@1`. |
| 500 | `internal_error` | Something failed on our side. | Retry; report the request id if it persists. |

## Streams

A stream that fails after content was sent ends with an error chunk, then `[DONE]`:

```
data: {"error":{"message":"stream interrupted by provider failure; delivered tokens are not billed without a verified receipt","type":"server_error","code":"stream_interrupted"}}
```

Two codes can appear there. `stream_interrupted` means the provider stopped or disconnected. `provider_output_invalid` means the provider's reply failed validation, for example a tool call that could not be delivered, a reply that kept repeating itself, or a reply that ended with nothing delivered. In both cases nothing is charged for that attempt. Send the request again.

A reasoning model's thinking arrives under `reasoning_content` in the message or the delta, before the answer. It is shown and it counts as output tokens at the model's output price, but it is never the answer: a reply that only reasoned and never answered is refused like an empty one.

## Agent runs paid from a wallet

The product API refuses a budget or a run when the wallet paying for it cannot: `wallet_required`, `wallet_insufficient_funds`, `wallet_unpaid_limit`, `wallet_payment_failed` and `wallet_unavailable`. [Pay for runs from your wallet](https://docs.katara.com/products/wallet-budgets.txt#refusals) says what each means. A run paid per run with x402 has its own refusals, listed under [run errors](https://docs.katara.com/developers/x402.txt#run-errors).

## Wallet-paid requests

A request paid per call is bound to the provider or vendor quoted in its `402` challenge. If it fails before delivering anything, a named model answers `502 provider_failed` and nothing is charged; request a new challenge. For `katara/cortex@1` the answer is a fresh `402` for the next candidate: sign it and retry, the first authorization expires unused. Each address may hold a limited number of unpaid quotes; past it the answer is `429 quote_rate_limited` with `Retry-After`. [Pay per request with x402](https://docs.katara.com/developers/x402.txt#errors) lists the payment errors and those of the Responses API.