rate_limit_exceeded

Rate limiting — per-minute request limits and retry guidance

HTTP status: 429
Category: API rate limiting

What this error means

Your tenant exceeded the per-minute request limit for the Customer API. The canonical error code is rate_limit_exceeded; rate_limited is a legacy alias with identical behaviour.

Rate limiting protects platform stability. It is distinct from quota_exceeded (403), which indicates a plan resource cap rather than a transient throughput limit.

Common causes

Tight polling loops against list endpoints
Bulk migration scripts without delays between requests
Multiple services sharing one management API key
Burst traffic after a deploy or cron job

How to fix it

Read retry_after from the error (or the Retry-After response header) and wait before retrying.
Enable automatic retries in the SDK — WochaClient retries transient 429 responses with backoff by default.
Reduce request volume: batch operations, cache reads, or use webhooks instead of polling.
Upgrade your plan for a higher rate limit tier.

Rate limit tiers

Tier	Limit
Free	100 req/min
Starter	500 req/min
Pro	2,000 req/min
Enterprise	10,000 req/min

Example

import { WochaRateLimitError } from "@wocha/sdk";
 
try {
  await wocha.logs.list({ page_size: 50 });
} catch (err) {
  if (err instanceof WochaRateLimitError) {
    const delayMs = (err.retryAfter ?? 60) * 1000;
    console.warn(`Rate limited — retry after ${delayMs / 1000}s`, err.docsUrl);
    await new Promise((r) => setTimeout(r, delayMs));
    return wocha.logs.list({ page_size: 50 });
  }
  throw err;
}