Rate limits

Nucleus is currently lightweight on rate-limiting. We document what exists; if your automation hits limits you don't see here, please report it.

Per-IP login bucket

POST /auth/login and POST /auth/forgot-password share an in-memory token bucket: 5 attempts per IP per minute. Exceeding it returns 429 with too many login attempts (login) or too many requests (forgot-password).

This protects against credential-stuffing and email-enumeration. It's not a general API rate-limit — bearer-token requests don't go through it.

API endpoints

There's no per-token or per-IP limit on Authorization: Bearer … requests at the moment. Behave reasonably:

• Don't poll resources that have an SSE stream — subscribe to the federation events stream instead.
• Use cursor pagination (before parameter) instead of repeatedly fetching the same window.
• Respect the response — if you get a 5xx, back off exponentially before retrying.

We may introduce per-token limits before v1. They will land with at least 30 days' notice via the changelog and an email to all customers with active tokens.

When a request gets capacity-rejected

If the control plane is overloaded (rare but possible), you might see:

• 503 Service Unavailable — load shedding. Retry with backoff.
• 504 Gateway Timeout — request took longer than the ingress allows. Same advice.

Neither is a rate limit per se; they're symptoms of the same underlying signal.

When provisioning is queue-throttled

POST /api/federations/:id/spokes writes the row synchronously but defers the actual Helm install to a background queue. The queue runs serially within a federation, so submitting 20 spokes back-to-back doesn't fan out to 20 parallel Helm installs — they queue and process one at a time. The API doesn't reject; it just takes a while. Watch the events stream for completion.