Errors and limits

Every failure is the same shape — { "error": "..." } with a status code that means something. This page maps each code to a cause and a fix, then lists the limits worth knowing before you hit them.

The error shape#

{ "error": "Your credit balance is exhausted. Add credits to continue transcribing." }

That is the whole body. Messages are stable and safe to match on, and they never echo your request back — no URLs, no vocabulary, no credentials.

Status codes#

Errors that are not HTTP errors#

A transcript can fail after it was accepted. The create call returns 200, and the failure shows up on the object:

{
  "id": "tr_9k2mQvR7pKd3sTn1yBhL",
  "status": "error",
  "error": "Parakeet does not support the requested language: ja",
  "words": null,
  "text": null
}

Always branch on status before reading words. Common causes:

Failed transcripts are not billed — metering only counts completed audio.

Size limits#

An empty upload body is rejected too: 400 with {"error":"The uploaded audio file is empty."}.

Self-hosted deployments set their own upload limit — see Self-hosting.

Rate limits#

120 requests per minute per workspace by default, counted in fixed one-minute windows across every endpoint. Over the limit:

{ "error": "Too many requests. Please retry shortly." }

POST /v2/upload also sets a retry-after header with the number of seconds until the current window resets. Other endpoints do not, but the window is always at most 60 seconds, so waiting a minute always clears it.

async function withRateLimitRetry<T>(call: () => Promise<T>): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await call();
    } catch (error) {
      if (!(error instanceof SandchestError) || error.status !== 429 || attempt >= 5) throw error;
      await new Promise((resolve) => setTimeout(resolve, Math.min(60_000, 2 ** attempt * 1000)));
    }
  }
}

The limit counts requests, not audio. Polling a long transcript every 75 milliseconds will hit it long before your uploads do — poll every second or two, or use a webhook and stop polling entirely.

Self-hosted deployments change it with SANDCHEST_RATE_LIMIT_PER_MINUTE.

Deadlines#

The SDK's polling timeout is a client-side deadline. When it expires the transcript keeps going — fetch it later by id.

Retrying safely#

Retries are only safe when they cannot create a second transcript. Send an Idempotency-Key on every creation request you might retry:

curl -sS https://stt-api.sandchest.com/v2/transcript \
  -H "Authorization: $SANDCHEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-8842" \
  -d '{"audio_url":"'"$UPLOAD_URL"'"}'

• Same key, same request → the original transcript, and no second charge.
• Same key, a different request → 409.
• No key → a second transcript, and a second charge.

Derive the key from something stable in your own system — a job id, a recording id, a content hash. Not a random value, or a retry after a crash will not match.

Verify#

Provoke each class of failure and check you get the code you expect:

API="https://stt-api.sandchest.com"

# 401 — no key
curl -sS -o /dev/null -w '%{http_code}\n' "$API/v2/transcript?limit=1"

# 400 — an option that does not exist
curl -sS -o /dev/null -w '%{http_code}\n' "$API/v2/transcript" \
  -H "Authorization: $SANDCHEST_API_KEY" -H "Content-Type: application/json" \
  -d '{"audio_url":"https://example.com/a.mp3","not_a_real_option":true}'

# 400 — an unknown transcript id on the compatibility endpoint
curl -sS -o /dev/null -w '%{http_code}\n' "$API/v2/transcript/tr_does_not_exist" \
  -H "Authorization: $SANDCHEST_API_KEY"

# 404 — the same id on the native endpoint
curl -sS -o /dev/null -w '%{http_code}\n' "$API/api/v1/transcripts/tr_does_not_exist" \
  -H "Authorization: $SANDCHEST_API_KEY"

401
400
400
404

Next#

Billing — what a second of audio costs and how credits work.