Rate limits & errors

Rate limits

Each API key has a per-minute (rate_limit_rpm) and per-day (rate_limit_rpd) limit. Exceeding either returns 429 Too Many Requests. Back off and retry using the Retry-After header.

Error format

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 30s."
  }
}

Status codes

• 400 — invalid parameters or body.
• 401 — missing or invalid x-api-key.
• 403 — origin/IP not allowed, or key lacks the required scope.
• 404 — resource not found in this workspace.
• 429 — rate limited.
• 5xx — transient server error; retry with backoff.

Best practices

• Handle 429 and 5xx with exponential backoff + jitter.
• Cache GET /v1/articles and /categories responses; they change rarely.
• Paginate rather than requesting huge per_page values.