Common errors
What the model-kind routes (embeddings, rerank and the routes that follow) return when a call does not run, and what to do about each one.
Error shape
Errors come back as JSON with a status code. Most carry error.message, error.type and error.code; act on code, which does not change, rather than the message. A call refused before the model runs costs nothing, and the messages that say Nothing was charged mean exactly that.
Recorded reply, 2026-11-13: HTTP 402 from a key with no credit.
{
"error": {
"message": "Not enough prepaid credit for this request (it may need 0.000002).",
"type": "invalid_request_error",
"code": "insufficient_credits"
}
}Codes on every model-kind route
These can come back from embeddings, rerank and the other model-kind routes. Each page lists its own input errors.
| Status | Code | Message | What to do |
|---|---|---|---|
401 | invalid_api_key | Invalid or missing API key. | Send Authorization: Bearer <key> with a key from the dashboard. |
428 | terms_not_accepted | Sign in at https://tirtha.ai/dashboard and accept the current Terms to continue. | Accept the Terms and Privacy Policy in the dashboard, then retry. The body is shown below. |
409 | terms_version_not_current | Sign in at https://tirtha.ai/dashboard and accept the current Terms to continue. | A newer version is out. Accept it in the dashboard, then retry. |
400 | unknown_parameter | Unknown field(s): <names>. | Remove the fields it names. No field is ever silently dropped. |
400 | invalid_request | Body must be a JSON object. | Send a JSON object with Content-Type: application/json. |
403 | model_not_allowed | This key cannot use <model>. | The key has a model list without this model. Use a key that can use it. |
402 | insufficient_credits | Not enough prepaid credit for this request (it may need <amount>). | Add credits. The amount, in US dollars, is the hold for this call: an upper estimate, not the bill. |
402 | billing_required | This needs a prepaid credit account. | Use a key that belongs to an account with credits. |
429 | quota_exceeded | Rate limit reached (rate limit <n>/min). | This key has a per-minute limit. Wait Retry-After (60 seconds). |
429 | spend_cap_reached | This key reached its daily spend cap. Requests are refused until 00:00 UTC; nothing was charged. | Wait until 00:00 UTC. Retry-After gives the seconds. |
429 | media_busy | This model is busy right now. Retry in a few seconds. Nothing was charged. | Retry after Retry-After (2 seconds). |
400 | content_policy | Refused by content policy. Nothing was charged. | Change the request. |
403 | media_suspended | This key is held from media requests for review after repeated content-policy refusals. Contact support. | Three content-policy refusals in 30 days hold the key from these routes. Email [email protected]. |
503 | unavailable | Temporarily unavailable. Nothing was charged. | Safe to retry the same call. |
503 | media_unavailable | Media is temporarily unavailable. Please retry. Nothing was charged. | Safe to retry shortly. |
503 | billing_unavailable | Billing is temporarily unavailable. Please retry. | Retry shortly. |
Terms not accepted
A 428 or 409 has a different body: error is a string, with links to both documents and the versions to accept. The versions below are examples.
{
"error": "terms_not_accepted",
"message": "Sign in at https://tirtha.ai/dashboard and accept the current Terms to continue.",
"terms_url": "https://tirtha.ai/terms",
"privacy_url": "https://tirtha.ai/privacy-policy",
"terms_version": "2026-10-29",
"privacy_version": "2026-10-29"
}Retrying
Retry only what says to.
429 media_busy,503 unavailable,503 media_unavailableand503 billing_unavailableare safe to retry as they are. Wait forRetry-Afterwhen it is sent.Do not retry a 400 unchanged.
A 400 is about the request itself. The same call gets the same answer; fix what the message names.
Back off on 429.
quota_exceededsendsRetry-After: 60,media_busysends 2, andspend_cap_reachedsends the seconds to 00:00 UTC.
Checked against the API code on 2026-11-14. Tīrtha is still being built; limits and fields may change, and this page changes with them.