Docs API
API errors and limits
Error codes, rate limits, safe retries and key security.
Updated November 2026
Errors
Every error has the same shape. Branch on code, since the wording of message may change. Quote request_id if you contact support.
{
"error": {
"code": "quota_exceeded",
"message": "You have used all 600 checks on the Enterprise plan this month.",
"request_id": "req_6f1c2a9e4b7d40c18a3e5d21",
"details": { "plan": "enterprise", "quota": 600, "used": 600 }
}
}| Status | Code | What to do |
|---|---|---|
| 401 | missing_api_key | Send your key in the header |
| 401 | invalid_api_key | The key is wrong or was revoked. Use another |
| 401 | api_key_expired | Create a new key |
| 402 | quota_exceeded | This month's checks are used up |
| 402 | video_too_long_for_plan | Use a shorter video |
| 403 | plan_required | The account is no longer on the Enterprise plan |
| 403 | insufficient_access | The key is read-only. Use a read and write key |
| 404 | not_found | It doesn't exist in this account |
| 409 | conflict | For example, the report isn't ready until the check finishes |
| 409 | idempotency_key_reused | That key was used for a different request. Use a new one |
| 409 | idempotency_in_progress | The first request is still running. Try again shortly |
| 422 | invalid_request | details.errors lists each field that's wrong |
| 422 | invalid_video_uri | Use the video_uri from POST /v1/uploads |
| 422 | invalid_report_language | The message lists the languages you can use |
| 429 | rate_limited | Wait for the seconds in Retry-After |
| 500 | internal_error | Our fault. Try again, and quote the request_id if it continues |
Rate limits
Your account can make 120 requests a minute. All of its keys share that limit. Every reply tells you where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed each minute |
X-RateLimit-Remaining | Requests left this minute |
X-RateLimit-Reset | Seconds until the count starts again |
Retry-After | On a 429 reply, how many seconds to wait |
Retrying safely
Starting a check spends from your allowance, so a retry after a network failure could use two. To prevent that, send an Idempotency-Key header with a value unique to that video, up to 200 characters.
- Send the same key again within 24 hours and you get the first check back, with
replayedset to true. Nothing new runs. - If the first request failed, nothing was created, and the same key can try again.
Retry on 429 and 500, and on network errors. Other errors will fail the same way until you change the request.
Keeping keys safe
- Give each system its own key, so you can turn one off without affecting the rest.
- Use read only unless the system needs to upload videos or start checks.
- Set an expiry date. Before it arrives, create a new key, move your system to it, then revoke the old one.
- If a key may have leaked, revoke it straight away. It stops working on the next request.
We store a fingerprint of each key rather than the key itself, so we can't show it to you again. Creating and revoking keys appears in your Activity log, and so do the checks and report downloads a key makes.