Errors & Troubleshooting

Use this page when a request fails or behaves unexpectedly. Endpoint reference pages document per-field validation; this page explains what failed, how to fix it, and how to retry safely.

Error response shape

Most REST errors return JSON:

{
  "error": {
    "message": "Human-readable description",
    "code": "invalid_request_error"
  }
}

Some endpoints add their own codes for product-specific rules, for example Document Digitization returns invalid_request_error (400) when a file exceeds the 10-page limit. These are listed in the “Errors” section of each API guide.

HTTP status quick reference

Out of credits (402)

A 402 means the organisation’s credit balance is empty, not that you are being rate limited. The balance is shared by every workspace, API key and product, so a 402 from one service means the whole organisation is out of credits.

{
  "error": {
    "message": "No credits available.",
    "code": "insufficient_quota_error"
  }
}

To recover:

1. Add credits on Settings → Billing. See Billing & payments.
2. Turn on Auto-Recharge so a low balance tops up before production traffic stops.
3. Retry the failed request once credits land. No key rotation or redeploy is needed.

Rate limits and capacity (429)

Every 429 says “not now”, but four different codes sit behind it and they need different responses:

Only the first is your own quota. Treating all four as “rate limited, back off” leaves an exhausted seat budget looking like a temporary blip.

SDK handling (Python)

from sarvamai import SarvamAI
from sarvamai.core.api_error import ApiError
client = SarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
try:
    response = client.speech_to_text.transcribe(
        file=open("audio.wav", "rb"),
        model="saaras:v4",
        mode="transcribe",
    )
except ApiError as e:
    if e.status_code == 403:
        print("Check SARVAM_API_KEY, auth uses 403, not 401")
    elif e.status_code == 402:
        print("Credits exhausted, add credits on Settings -> Billing")
    elif e.status_code == 429:
        # rate limit, model capacity, or seat budget: check e.body["error"]["code"]
        print("Rate limited or out of capacity, retry after delay")
    else:
        print(e.status_code, e.body)

SDK handling (JavaScript)

import { SarvamAIClient } from "sarvamai";
const client = new SarvamAIClient({
  apiSubscriptionKey: process.env.SARVAM_API_KEY,
});
try {
  const response = await client.speechToText.transcribe({
    file: audioFile,
    model: "saaras:v4",
    mode: "transcribe",
  });
} catch (err) {
  // SDK wraps HTTP errors, inspect status and body
  // 402 = out of credits, 429 = rate limit / capacity / seat budget
  console.error(err.statusCode, err.body);
}

Retry with exponential backoff

Use retries only for 429, 500, 502 and 503: not for 400, 402, 403 or 422. A 402 needs credits, not another attempt, and a 429 carrying seat_budget_exhausted_error needs a top-up rather than a backoff.

import time
def call_with_backoff(fn, max_retries=5):
    delay = 1.0
    for attempt in range(max_retries):
        try:
            return fn()
        except ApiError as e:
            if e.status_code not in (429, 500, 502, 503) or attempt == max_retries - 1:
                raise
            time.sleep(delay)
            delay = min(delay * 2, 60)

Common pitfalls

Support workflow

1. Note timestamp, endpoint, and error.code from the response body.
2. Reproduce with curl or SDK using the smallest failing request.
3. Check API Status for incidents.
4. Contact support via Talk to us with request ID if available.

Related pages

• Authentication
• Credits & Rate Limits
• Billing & payments
• Pricing
• SDKs & Libraries