Rate limits
Ceilings and how to back off.
Every /api/v1 request counts against one ceiling, per client IP, in a fixed one-minute window:
| Scope | Ceiling |
|---|---|
All /api/v1 requests, per IP | 600 / minute |
Past the ceiling the edge answers 429 before the request reaches the API. The window is fixed, so
the count resets at the top of the next minute rather than sliding.
The agent endpoint runs a model on every call. Treat the ceiling as a budget, not a target.
Backing off
Retry on 429 and 503, with exponential backoff and jitter. Do not retry 4xx responses other
than 429 — a 403 will not start working because you asked again.
If the agent endpoint returns 429, retrying in a tight loop is the worst response: you will stay
at the ceiling and never make progress. Wait for the reset.
Retrying the agent safely
POST /agent/invoke accepts an Idempotency-Key header:
curl -X POST https://app.superposition.ai/api/v1/agent/invoke \
-H "Authorization: Bearer $SUPERPOSITION_API_KEY" \
-H "Idempotency-Key: 8f31c0a4-..." \
-H "Content-Type: application/json" \
-d '{"prompt": "How many candidates are awaiting review?"}'A repeat of the same key returns the original result instead of running the agent again. Use a fresh key per logical request and reuse it across retries of that request. Without one, a network retry runs the agent twice and you pay twice.
The response tells you which happened:
{ "sessionId": "...", "reply": "...", "status": "completed", "idempotentReplay": true }status has three values, and each one tells you what to do next:
status | What happened | What to do |
|---|---|---|
completed | The run finished. reply holds the answer. | Nothing. |
in_progress | A retry arrived while the first run is still going. reply is null. | Poll GET /api/v1/agent/sessions/{sessionId}. Do not invoke again. |
failed | The original run for this key died. reply is null. | Retry with a new key, or investigate first. |
failed is terminal. Reusing that key will keep returning failed — it will never turn into
completed, so retrying it forever is pointless:
{
"sessionId": "...",
"reply": null,
"status": "failed",
"idempotentReplay": true,
"error": "The agent run did not complete.",
"failedCorrelationId": "3f7c1e02-95a4-4a6d-9c5a-1b0e2f8d4a71"
}Quote failedCorrelationId in a support request — it points at the run that actually died, not at
your replay.
Do not send Idempotency-Key together with sessionId. The key applies to a session's first
invocation, so the combination is refused with 400 invalid_request rather than accepted under a
guarantee it cannot keep. Resume a conversation without the header, or start a new session with it.
Retrying with a new key runs the agent again from the start. A failed run may already have had side effects, so treat a new key as a deliberate decision rather than an automatic retry.
Last updated on