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:

1
{
2
  "error": {
3
    "message": "Human-readable description",
4
    "code": "invalid_request_error"
5
  }
6
}

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

HTTP status quick reference

SDK handling (Python)

1
from sarvamai import SarvamAI
2
from sarvamai.core.api_error import ApiError
3
4
client = SarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
5
6
try:
7
    response = client.speech_to_text.transcribe(
8
        file=open("audio.wav", "rb"),
9
        model="saaras:v3",
10
        mode="transcribe",
11
    )
12
except ApiError as e:
13
    if e.status_code == 403:
14
        print("Check SARVAM_API_KEY — auth uses 403, not 401")
15
    elif e.status_code == 429:
16
        print("Rate limited — retry after delay")
17
    else:
18
        print(e.status_code, e.body)

SDK handling (JavaScript)

1
import { SarvamAIClient } from "sarvamai";
2
3
const client = new SarvamAIClient({
4
  apiSubscriptionKey: process.env.SARVAM_API_KEY,
5
});
6
7
try {
8
  const response = await client.speechToText.transcribe({
9
    file: audioFile,
10
    model: "saaras:v3",
11
    mode: "transcribe",
12
  });
13
} catch (err) {
14
  // SDK wraps HTTP errors — inspect status and body
15
  console.error(err.statusCode, err.body);
16
}

Retry with exponential backoff

Use retries only for 429, 500, and 503 — not for 400/403/422.

1
import time
2
3
def call_with_backoff(fn, max_retries=5):
4
    delay = 1.0
5
    for attempt in range(max_retries):
6
        try:
7
            return fn()
8
        except ApiError as e:
9
            if e.status_code not in (429, 500, 503) or attempt == max_retries - 1:
10
                raise
11
            time.sleep(delay)
12
            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
• Pricing
• SDKs & Libraries