Tīrtha is still being built, so some features and models may not work as expected yet. Billing always follows the prices shown. Something broken? Email [email protected].

Tīrtha

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.

StatusCodeMessageWhat to do
401invalid_api_keyInvalid or missing API key.Send Authorization: Bearer <key> with a key from the dashboard.
428terms_not_acceptedSign 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.
409terms_version_not_currentSign 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.
400unknown_parameterUnknown field(s): <names>.Remove the fields it names. No field is ever silently dropped.
400invalid_requestBody must be a JSON object.Send a JSON object with Content-Type: application/json.
403model_not_allowedThis key cannot use <model>.The key has a model list without this model. Use a key that can use it.
402insufficient_creditsNot 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.
402billing_requiredThis needs a prepaid credit account.Use a key that belongs to an account with credits.
429quota_exceededRate limit reached (rate limit <n>/min).This key has a per-minute limit. Wait Retry-After (60 seconds).
429spend_cap_reachedThis 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.
429media_busyThis model is busy right now. Retry in a few seconds. Nothing was charged.Retry after Retry-After (2 seconds).
400content_policyRefused by content policy. Nothing was charged.Change the request.
403media_suspendedThis 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].
503unavailableTemporarily unavailable. Nothing was charged.Safe to retry the same call.
503media_unavailableMedia is temporarily unavailable. Please retry. Nothing was charged.Safe to retry shortly.
503billing_unavailableBilling 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

  1. Retry only what says to.

    429 media_busy, 503 unavailable, 503 media_unavailable and 503 billing_unavailable are safe to retry as they are. Wait for Retry-After when it is sent.

  2. 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.

  3. Back off on 429.

    quota_exceeded sends Retry-After: 60, media_busy sends 2, and spend_cap_reached sends 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.