Errors and Rate Limits

Error envelope

All errors follow a single envelope:

{
  "errors": [
    {
      "code": "URLS_LIMIT_EXCEEDED",
      "message": "Maximum 100 URLs per request for priority=high.",
      "field": "urls"
    }
  ]
}

errors is always an array. field is only present on validation errors.

Error codes

Code	HTTP	Trigger
UNAUTHENTICATED	401	Missing, invalid, expired, or wrong-type token.
WEBSITE_NOT_FOUND	404	Website does not exist.
FORBIDDEN	403	Token's user has no access to the website, or too low a role for the endpoint.
VALIDATION_FAILED	400	Invalid request body: an empty URL array, an invalid URL or priority, or a Data Explorer parameter the endpoint cannot honour. field names the offending parameter.
MODULE_REQUIRED	403	The website has no platform module.
LIMIT_EXCEEDED	403	A plan limit for this billing cycle is spent.
URLS_LIMIT_EXCEEDED	400	URL count exceeds the priority's cap.
RATE_LIMITED	429	Per-website request cap or auth-failure cap hit.
EXPLORER_NOT_FOUND	404	Unknown or unexposed Data Explorer key.
EXPORT_NOT_FOUND	404	No such export for this account on this website.
EXPORT_SLOT_BUSY	409	Another export is already running for this account.
UPSTREAM_REJECTED	400	The request was rejected downstream for a user-correctable reason; the message says why.
UPSTREAM_UNAVAILABLE	502	Temporary internal failure. Retry.
INTERNAL_ERROR	500	Unhandled exception.

Rate limits

• 60 requests per minute per website. Exceeding this returns 429 RATE_LIMITED with a Retry-After header.
• 20 authentication failures per minute per source IP also return 429.

Standard headers on rate-limited responses:

• Retry-After
• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Batch URLs into as few requests as possible (up to 1000 URLs per call at priority=normal) rather than sending one request per URL.