Rate limits

The API limits how many requests you can make in a given window. When you exceed it, requests are rejected with 429 until the window resets.

When you're rate limited

A rate-limited request returns 429 Too Many Requests with a Retry-After header and the standard error envelope:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{
  "status": 429,
  "detail": "Too many requests.",
  "code": "b1a2c3d4-0000-0000-0000-000000000000"
}

The Retry-After header tells you how many seconds to wait before retrying. Only 429 indicates rate limiting — 5xx responses are server errors, handled separately under Recommended backoff.

Limits

TBD, API team to confirm the numeric limits: requests per second/minute, whether limits are per API key or per client, and any separate limits for batch endpoints. Until published here, your specific limits are provided with your credentials.

Recommended backoff

Handle 429 (and retryable 5xx) responses with this order of preference:

1. Honor Retry-After first. If the header is present, wait exactly that long before retrying.
2. Otherwise, exponential backoff with jitter. Double the wait each attempt and add a small random offset so retries don't cluster.
3. Cap retries. Give up after a few attempts and surface the error rather than retrying forever.

async function withRetry(request: () => Promise<Response>, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await request();
    if (res.status !== 429 && res.status < 500) return res;

    const retryAfter = Number(res.headers.get("Retry-After"));
    const backoff = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : 2 ** attempt * 500 + Math.random() * 250; // exponential + jitter

    await new Promise((r) => setTimeout(r, backoff));
  }
  throw new Error("Exhausted retries");
}

Avoiding rate limits

• Batch where you can. Submit multiple credentials in one POST /v2/credentials call instead of one request per credential, but stay within the batch size limits or you'll get invalid_batch_size / max_batch_size_exceeded (see Errors).
• Prefer webhooks over polling. Register a webhook so Propelus notifies you when work completes, instead of repeatedly polling for results.
• Space out pagination. When iterating large result sets, add a short delay between pages (see Pagination).