Errors
Error codes and handling
Errors
All errors return JSON with an error field:
{ "error": "Error message here" }Error Codes
| Status | Error | What to do |
|---|---|---|
400 | url query parameter is required | Add url param |
400 | format must be json, srt, text, or vtt | Use a supported format |
400 | Unsupported URL | Use a supported platform URL |
401 | Missing X-API-Key header | Add X-API-Key header |
401 | Invalid API key | Check your key is correct and active |
401 | API key expired | Create a new key in the dashboard |
402 | Insufficient credits | Buy more credits or upgrade plan |
404 | This video isn't available for transcription. | Source removed/private — try another URL |
422 | No spoken audio detected in this video. | Video has no speech — nothing to transcribe |
429 | Rate limited. Try again in a moment. | Back off and retry |
499 | Transcript request was cancelled. | Client or server cancelled before completion |
502 | Failed to dispatch job / Could not reach the video. Try again or use a different URL. / Transcript generation failed. Try again. | Retry — upstream/pipeline issue. Credit was refunded. |
503 | Transcription service is temporarily unavailable. Try again. | Provider downtime — retry with backoff |
504 | Transcript generation timed out. Try again. | Retry — video may be long or service is slow. Credit was refunded. |
Failed requests (5xx) refund the deducted credit.
Retry Strategy
- 4xx errors — Fix the request, don't retry blindly (except
429) - 402 — Buy credits, then retry
- 429 — Back off and retry
- 502/503/504 — Retry with exponential backoff
async function transcribe(url: string, apiKey: string, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(
`https://scriptbase.app/api/v1/transcribe?url=${encodeURIComponent(url)}`,
{ headers: { "X-API-Key": apiKey } }
);
if (response.ok) return response.json();
// Retry 429 (rate limited) and 5xx; bail on other client errors.
if (response.status < 500 && response.status !== 429) {
throw new Error(await response.text());
}
// Exponential backoff for server errors
await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
}
throw new Error("Max retries exceeded");
}