Errors

The API uses standard HTTP status codes and returns structured error responses.

Error Response Format

All errors return a JSON object with these fields:

json

{
  "status_code": 400,
  "error_code": "INVALID_REQUEST",
  "detail": "The URL provided is not supported."
}

HTTP Status Codes

Code	Meaning
200	Success
201	Resource created
204	Deleted (no content)
400	Bad request - invalid parameters
401	Unauthorized - missing or invalid token
403	Forbidden - insufficient permissions or expired plan
404	Not found
422	Validation error
429	Rate limit exceeded
500	Internal server error

Error Codes

Error Code	Status	Description
`INVALID_REQUEST`	400	The request body or parameters are invalid
`INVALID_URL`	400	The provided URL is not supported or malformed
`AUTH_HEADER_TOKEN`	401	Missing or invalid X-AUTH-TOKEN header
`TOKEN_EXPIRED`	403	The API token has expired
`PLAN_EXPIRED`	403	Your subscription has expired
`PLATFORM_NOT_ALLOWED`	403	Platform not available on your tier
`DAILY_LIMIT_EXCEEDED`	429	Daily export creation limit exceeded (Premium only — Business is unlimited)
`RATE_LIMIT_EXCEEDED`	429	Per-5-minute export creation window exceeded (Premium 20, Business 60 — bulk excluded)
`CONCURRENCY_RATE_LIMIT`	429	Too many concurrent exports (Premium 1, Business 5 per token)
`QUEUE_LIMIT_EXCEEDED`	429	Too many queued exports (Premium 3, Business 5 per token)

See Rate Limits for the full per-tier matrix.

Rate Limit Error Response

When rate limited, the response includes a seconds_to_wait field:

json

{
  "status_code": 429,
  "error_code": "RATE_LIMIT_EXCEEDED",
  "seconds_to_wait": 42,
  "detail": "Rate limit exceeded. You have created 60 exports in the last 5 minutes (limit: 60). Retry in 42 seconds."
}

seconds_to_wait reflects when the oldest in-window export rolls out, so the value adapts to your actual usage shape (typically 30–120 s for steady traffic, up to 4 min if you submitted all your exports in a single burst).