Error handling

Every response carries a standard HTTP status code. Check it before you parse the body.

Status codes

Status	Description
400	Invalid request parameters
401	Missing or invalid API key
403	Not permitted for this account
404	Resource not found
409	Too many batches already queued or processing
429	Rate limit exceeded, daily Discovery limit reached, batch limit hit, or Discovery fair-use cap reached
500	Internal server error
502	Bad gateway — retry with backoff
503	Temporary service unavailability

Error response structure

Error bodies vary by type. Validation errors return error as an object of field errors; authentication and permission errors return detail; most other errors return error as a string plus an error_code — a short, stable slug such as insufficient_credits or creator_not_found. Branch on error_code where it is present rather than on the message text; treat it as optional.

Examples:

Validation error (400)

{
  "error": {
    "platform": ["\"foo\" is not a valid choice."]
  }
}

Authentication error (401)

{
  "detail": "Authentication credentials were not provided."
}

Rate limit exceeded (429)

{
  "error": "Too many requests. Please try again later.",
  "error_code": "throttled",
  "retry_after": 42
}

The response also includes a Retry-After header with the same value (seconds to wait).

Which `429` did you get?

Cause	How to recognize it	What to do
Rate limit	`error_code` is `throttled`	Wait the stated seconds, then retry with backoff
Daily Discovery limit	`error_code` is `daily_limit_exceeded`	Retry after the wait
Batch limits	`error_code` is `batch_rate_limit` or `polling_too_frequent`	Retry after the wait
Discovery fair-use cap reached	Body has `error` only — no `error_code`	Do not retry — it lifts at renewal, not on a timer

Every 429 except the fair-use cap carries retry_after and a Retry-After header.

See Usage, pricing, and limits for how the cap works.

Handling errors in your client

Always inspect the HTTP status code first.
Do not retry 4xx errors other than 429 unless the request is modified.
Retry transient errors — 5xx, and every 429 except the Discovery fair-use cap — using exponential backoff.
The Discovery fair-use cap 429 is not transient — retrying will not clear it. It lifts when your subscription renews, or sooner if we raise your cap.