Rate limits and errors
Found this helpful? Share it:
Found this helpful? Share it:
When a request fails, the idapt API tells you exactly why in a predictable shape, so your code can react instead of guessing. This is the error envelope, the types to branch on, and the limits to expect 🚦
Every failed request returns the same JSON shape:
{
"error": {
"type": "rate_limit",
"message": "Too many requests",
"code": "completions_per_minute"
}
}Branch on type, never on the wording of message(which can change). The optional code narrows the reason when one type covers several
cases.
Status | type | What happened |
|---|---|---|
|
| The key is missing, malformed, or revoked. |
|
| The key lacks the scope, or the route is session only. |
|
| No such resource, or you cannot see it. |
|
| The route exists but not this verb (for example creating a computer directly). |
|
| The body failed validation. Read the message for the field. |
|
| You hit a per-surface limit. Back off and retry. |
Every response carries an X-Request-Id header. Log it and
quote it when you contact support, because it points straight at the
failing request.
Surface | Limit |
|---|---|
Compatible-gateway completions | 60 requests per minute |
Notification sends | 100 per 24 hours per principal |
Notifications to one recipient | 500 per hour |
Automation webhook fires | 60 per hour |
Model calls also respect your plan allowance and Credit balance. When those run out you get a usage wall, not a rate limit. See Plans, allowances, and credits.
A usage wall carries a stable code naming which limit you
hit, so your integration can tell the user the right remedy:
code | What it means |
|---|---|
| The free tier's daily allowance is spent. Wait for the refill or subscribe. |
| The request needs an active subscription, for example a credits-billed feature without a plan. Nothing refills here: subscribing is the remedy. |
| A subscriber's included usage is spent and pay-as-you-go is off. Enable pay-as-you-go or upgrade. |
| The weekly premium-model budget is spent. Switch to a standard model, enable pay-as-you-go, or upgrade. |
| The Credit balance is empty. Add credits. |
| The monthly pay-as-you-go cap is reached. Raise the cap. |
On the OpenAI-, Anthropic-, and OpenRouter-compatible gateways, a key
on the free tier gets a 403 with code free_tier_requires_subscription: the external API needs a
subscription, while the free allowance stays available in the idapt
app.
On a 429, wait and retry with a growing delay rather than
hammering the endpoint. A simple pattern:
async function withRetry(call, tries = 4) {
for (let attempt = 0; attempt < tries; attempt++) {
const res = await call();
if (res.status !== 429) return res;
await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
}
throw new Error("rate limited after retries");
}The JavaScript SDK throws a typed RateLimitError you can
catch directly. See the SDK quickstart.
Related articles
REST API
Authentication, versioning, response shapes, pagination, and errors for the idapt REST API, plus the full endpoint list.
Notifications API
Send notifications to workspace members and manage your inbox programmatically.
Automations and webhooks
Run an agent on a schedule, or fire one from an external system with a signed webhook.
Was this helpful?