Errors

Errors use the OpenAI envelope:

{ "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 says what each means. A run paid per run with x402 has its own refusals, listed under 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 lists the payment errors and those of the Responses API.