Errors and limits
HTTP errors, batch errors, and the limits that apply to the public API.
The public API returns errors as { "error": "<machine-readable message>" } with a conventional HTTP status. Batch-level business errors come back inside a 202 or 429 response as batchError.
HTTP status codes
| Status | error value | Cause |
|---|---|---|
| 400 | invalid json, urls must be a non-empty string array, idempotency-key required, idempotency-key must be 255 characters or fewer | The request body or the idempotency header failed validation |
| 401 | missing bearer token, invalid api key | No Authorization: Bearer header, or the key does not exist |
| 403 | api key lookup failed, scope denied | The key lookup failed, or the key lacks the required scope |
| 404 | not found | The task ID does not exist or belongs to another account |
| 409 | idempotency conflict | The same Idempotency-Key arrived with a different body |
| 413 | batch too large | More than 100 URLs, or the body exceeds about 900 KB |
| 425 | request is still processing | The same idempotency key is still in flight. Retry after Retry-After seconds |
| 429 | rate limit exceeded | Too many requests. Honor the Retry-After header |
| 500 | processing failed, task lookup failed | A server-side failure. The idempotent replay returns the same error |
Batch errors
When the whole batch fails on an account or billing limit, POST /api/v1/urls returns 429 with batchError set. A 202 response can also carry batchError: null plus per-URL rejectedUpfront entries.
batchError | Cause |
|---|---|
batch_too_large | More than 100 URLs in one request |
first_order_limit | Batches over 50 URLs require at least one paid order on the account |
daily_limit | The account passed its daily submission cap of 2,000 URLs |
insufficient_credits | The credit balance or pending volume cannot cover the batch |
account_unavailable | The account is banned or unavailable |
Rate limits
Two sliding-window limits apply, both defaulting to one minute.
| Limit | Default | Scope |
|---|---|---|
| Per IP | 30 requests / minute | publicApiIp |
| Per API key | 120 requests / minute | publicApiKey |
A 429 response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers.
Per-URL rejection reasons
URLs rejected during intake validation appear in rejectedUpfront and do not consume credits. See Submit URLs for the full table.