Developer Manual

Rate Limits & Plans

API access is included on the Growth and Enterprise plans. Requests are rate limited by endpoint type, and each plan has a daily call limit. When you go over a limit the API returns 429 with a Retry-After header.

Plan requirement

API access is switched on for the Growth and Enterprise plans only. Growth has a daily cap of 50,000 calls on top of its monthly credit allowance. Enterprise has no daily call cap. Starter, Pro and Team do not include API access, and a call from an organization on one of those plans returns 403.

Note:A 403 here means the org's plan does not include the API. A 403 Insufficient scope is different: it means the key lacks a required scope. The SDK raises both as PermissionError.

Rate limiters

There are two limiters. The endpoint that starts runs has a stricter one than the read endpoints. Going over either returns 429.

Strict limiter	POST /v1/run, the endpoint that starts a run.
Standard limiter	Read and management endpoints: GET /v1/runs, /v1/runs/:id, /v1/triage, triage approve/reject.
Daily limit	A daily call cap per plan, checked after authentication. Going over it returns 429.

Handling 429

A 429 response includes a Retry-After header in seconds. Back off for at least that long before retrying.

bash

# A 429 carries Retry-After (seconds).
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{ "error": "Rate limit exceeded" }

The SDK parses the header into RateLimitError.retryAfter:

typescript

import { RateLimitError } from "@eclips/sdk";

try {
  await client.runAndWait("ap_specialist", task);
} catch (err) {
  if (err instanceof RateLimitError) {
    const wait = err.retryAfter ?? 60; // seconds, from Retry-After
    await new Promise((r) => setTimeout(r, wait * 1000));
    // …then retry
  }
}

Credits vs. rate limits

Rate limits count requests. Credits count the work agents do. Running out of credits is not the same as being rate limited. Check your /v1/usage summary and the response error message to tell them apart.

Tip:Read your current balance any time with GET /v1/usage (scope agents:read). On unlimited plans credits_remaining is null.

← PreviousBatches Next →Errors