Errors & rate limits
HTTP status codes the Specala AI API returns (401, 403, 422, 429, 5xx), the JSON error shape, what triggers each one, and how to handle rate limits.
The API uses standard HTTP status codes. 2xx means success; 4xx means something about the
request needs fixing.
Status codes
| Status | Meaning | Typical cause |
|---|---|---|
200 | OK | Request succeeded. |
201 | Created | Key created (management). |
204 | No Content | Key revoked (management). |
401 | Unauthorized | Missing/invalid/expired key, or key passed in the URL. |
403 | Forbidden | Plan without API access (api_access_denied). |
404 | Not Found | Resource doesn't exist in your workspace. |
422 | Unprocessable Entity | Invalid parameter (e.g. bad format, too many ids). |
429 | Too Many Requests | Rate limit exceeded. |
5xx | Server error | Transient — retry with backoff. |
Error shape
Most errors return a JSON body with a detail field. Plan/access errors include a machine-readable
code:
{
"detail": {
"code": "api_access_denied",
"message": "Your current plan does not include API access. Please upgrade to a plan with API & MCP support."
}
}{
"detail": "Invalid API key"
}Common cases
| What you see | Why | Fix |
|---|---|---|
401 on every call | Key revoked, expired, or has a trailing space | Create a fresh key, copy carefully |
401 with a key in the query string | Keys in URLs are rejected by design | Move the key to the Authorization header |
403 api_access_denied | Plan without API & MCP | Upgrade to Pro or Expert |
404 on a known ID | The transcription is in another workspace | Use a key for that workspace |
422 on export | format isn't md/txt, or ids is empty/over 100 | Fix the parameter |
Rate limits
Limits are per key:
| Surface | Limit |
|---|---|
| Data endpoints (list / get / export / bulk) | 500 requests / minute |
| Key management | 180 requests / minute |
When you exceed a limit you get 429. Handle it gracefully:
- Back off, don't retry immediately. Wait a few seconds and try again.
- Avoid tight loops. To export many transcriptions, use Bulk export (one request) instead of looping over single exports.
- Spread work out rather than firing hundreds of calls at once.
Don't auto-retry on 429 instantly
Immediate automatic retries make the limit worse. Use exponential backoff (e.g. 1s, 2s, 4s).