Skip to main content

Errors and limits

Errors use a stable JSON shape:
field, suggestedFix, allowedValues, and writableFields are included when the server can provide a precise recovery hint. AI agents should use those fields to correct the payload instead of guessing.

Common error codes

Recovery fields

Example non-writable field error on /api/v1/subscriptions:

Scopes and plan gating

  • Scopes: A read key can list and read subscriptions, read notification settings, and call analytics and audit endpoints. A write key additionally allows create, update, delete, and notification settings updates. A write call made with a read-only key returns 403 insufficient_scope; do not retry — request a write-scoped key. See Authentication.
  • Premium analytics: /api/v1/analytics/duplicates and /api/v1/analytics/optimizations return 403 premium_required on Free accounts. /api/v1/analytics/summary is available on all plans.

Rate-limit headers

Authenticated /api/v1/* responses include:
  • Default authenticated quota: 60 requests per minute per account (API_RATE_LIMIT_PER_MINUTE) on both Free and Premium plans.
  • X-RateLimit-Reset is a Unix timestamp in seconds indicating when the current 1-minute window resets.
  • Validation failures (400) on POST, PATCH, and query parameters are rejected before the per-minute quota is consumed, so they do not count against your limit and do not carry rate-limit headers. Fixing the payload and retrying is free.
  • Every 429 rate_limit_exceeded response (both per-minute user rate limits and hourly failed-auth lockouts) includes a Retry-After header with the number of seconds to wait before retrying:

CORS

The public API supports browser preflight requests:
Keep API keys out of public browser apps unless you fully trust the browser context. CORS support is intended for developer tooling, internal dashboards, and trusted local workflows.