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
readkey can list and read subscriptions, read notification settings, and call analytics and audit endpoints. Awritekey additionally allows create, update, delete, and notification settings updates. A write call made with a read-only key returns403 insufficient_scope; do not retry — request a write-scoped key. See Authentication. - Premium analytics:
/api/v1/analytics/duplicatesand/api/v1/analytics/optimizationsreturn403 premium_requiredon Free accounts./api/v1/analytics/summaryis 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-Resetis a Unix timestamp in seconds indicating when the current 1-minute window resets.- Validation failures (
400) onPOST,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_exceededresponse (both per-minute user rate limits and hourly failed-auth lockouts) includes aRetry-Afterheader with the number of seconds to wait before retrying: