Rate limits and retries

Every new API key is created with:

• 60 requests per minute (X-RateLimit-Limit)
• 1000 requests per hour

Both limits are enforced independently; the lower remaining value is reported in X-RateLimit-Remaining. Limits can be raised per-key by FlowBeacon support — contact partners@flowbeacon.ai.

Response headers

All successful authenticated responses carry:

Header	Description
X-RateLimit-Limit	Minute limit configured on the calling key.
X-RateLimit-Remaining	Minimum of remaining RPM and RPH windows.
X-RateLimit-Reset	Unix timestamp (seconds) when the RPM window resets.

On 429 responses an additional header is returned:

Header	Description
Retry-After	Seconds to wait before retrying.

Limit scope

Limits are scoped per API key, not per organization. If you need multiple keys with a shared budget contact support before designing around this.

Handling 429

Honor Retry-After. Add a small jitter to avoid thundering-herd retries.

import httpx, time

for attempt in range(5):
    r = httpx.post(url, headers=headers, json=body, timeout=30)
    if r.status_code != 429:
        r.raise_for_status()
        break
    wait = int(r.headers.get("Retry-After", "1"))
    time.sleep(wait + (0.2 * attempt))  # small jitter

async function withRetry<T>(send: () => Promise<Response>): Promise<T> {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await send();
    if (res.status !== 429) {
      if (!res.ok) throw new Error(await res.text());
      return res.json();
    }
    const wait = Number(res.headers.get('retry-after') ?? '1');
    await new Promise((r) => setTimeout(r, (wait + 0.2 * attempt) * 1000));
  }
  throw new Error('rate-limited after 5 attempts');
}

Designing around limits

• Batch evaluations. POST /evaluate accepts up to 10 scenario IDs per call.
• Cache the policy catalog. GET /governance/policies is safe to cache for 24 h.
• Use webhooks instead of polling. A polling loop at 2 s burns 30 RPM per evaluation.
• Backoff after complete. Stop polling immediately on terminal status.

Errors to retry vs. errors not to

Status	Retry?	Notes
429 Rate limit exceeded	Yes	Honor Retry-After.
500 Remediation generation failed	Yes	Transient. Cap at 3 retries with exponential backoff.
500 Internal server error	With caution	Include the request_id in any support ticket.
503 Public API is disabled	No	Emergency kill-switch. Check the status page.
4xx other than 429	No	Fix the request.

Next steps

• Error taxonomy — every documented error and its action.
• Sign requests with HMAC — remember to re-sign on every retry.