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	feature_not_supported	The model does not support tools, structured output, or reasoning as requested.	Check capabilities on /v1/models.
401	invalid_api_key	Missing or unknown key.	Create a key in the portal.
403	account_suspended	The account behind the key is suspended.	Contact support.
404	model_not_found	Unknown model id.	Use an id from /v1/models.
429	insufficient_quota	Spendable balance is below the request’s maximum cost.	Add USDC, raise the budget cap, or lower max_tokens. Honour Retry-After.
503	no_capacity	No provider can serve the model and no fallback applies.	Retry after Retry-After.
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 instead of [DONE]:

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

Nothing is charged for that attempt. Send the request again.