Docs / Reference / Errors & rate limits

Errors & rate limits

The standard response envelope, the error codes you'll encounter, and the rate-limit headers the API returns.

Every AskThis API response — success or error — uses the same JSON envelope, so you can parse it one way everywhere.

The envelope

{
  "data": { "...": "your result, or null on error" },
  "error": { "code": "ERROR_CODE", "message": "Human-readable explanation" },
  "meta": { "requestId": "req_..." }
}

On success, error is null. On failure, data is null and error is populated. Always log meta.requestId — quote it when you contact support.

Validation failures add a fields object pinpointing the offending inputs:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request",
    "fields": { "url": "Required" }
  },
  "meta": { "requestId": "req_..." }
}

Error codes

Status Code Meaning
401 UNAUTHORIZED Missing or invalid credentials
403 FORBIDDEN Authenticated, but not allowed (wrong role / org)
403 INSUFFICIENT_SCOPE The API key lacks a required scope
403 FEATURE_DISABLED The feature isn’t enabled for your plan
402 INSUFFICIENT_CREDITS Not enough AI credits for this action
404 NOT_FOUND The resource doesn’t exist or isn’t yours
409 ALREADY_EXISTS A conflicting resource already exists
422 VALIDATION_ERROR Input failed schema validation (see error.fields)
429 RATE_LIMITED Too many requests — back off (see below)

Codes are stable, uppercase strings — branch on error.code, not the message.

Rate limits

Rate-limited endpoints (for example scans and install pings) return standard headers on every response so you can self-throttle instead of hitting 429s:

Header Meaning
X-RateLimit-Limit Requests allowed in the current window
X-RateLimit-Remaining Requests left in the window
X-RateLimit-Reset Seconds until the window resets
Retry-After Seconds to wait before retrying (sent on 429)

When you exceed a limit you get a 429 with code RATE_LIMITED. Honor Retry-After and retry with exponential backoff.

Pagination

List endpoints return a bounded, sensible default set (most-recent first) — there is no cursor pagination today. Narrow results with the filters each endpoint documents (for example days on analytics), and use the CSV/PDF export for full history.

See also: API keys · Webhooks · API quickstart.