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, or text | Use json, srt, or text |
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 |
502 | Upstream service error | Retry — transcription service had an issue |
504 | Transcript processing timed out | Retry — video may be too long |
Retry Strategy
- 4xx errors — Fix the request, don't retry blindly
- 402 — Buy credits, then retry
- 502/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://api.scriptbase.app/api/v1/transcribe?url=${encodeURIComponent(url)}`,
{ headers: { "X-API-Key": apiKey } }
);
if (response.ok) return response.json();
// Don't retry client errors
if (response.status < 500) throw new Error(await response.text());
// Exponential backoff for server errors
await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
}
throw new Error("Max retries exceeded");
}