Limits and errors
The quotas a workspace runs on, how to read them from every response, and which errors to retry.
A product with many customers in one workspace shares one set of limits. This page lists the ones you meet in practice and how to handle each error your code will see.
Quotas
| Quota | Counted | When it runs out |
|---|---|---|
| Requests a day, REST and MCP together | Per workspace | 429 with api.quota_exceeded |
| DM replies an hour through the API and MCP | Per workspace, or per channel when limits.dmRepliesScope is channel | 429 with dm.too_many_replies or dm.channel_too_many_replies |
| DM replies an hour into one conversation | Per conversation, 20 on every plan | 429 with dm.conversation_too_many_replies |
| Channels | Per workspace | 402 with plan.limit_reached when connecting |
The numbers for each plan are in Workspaces and limits. GET /v1/me returns the ones that apply to your workspace right now, including any raised by eksis support.
Read the quota from each response
Every authenticated response carries three headers:
| Header | Value |
|---|---|
x-ratelimit-limit | The daily request quota of the workspace. |
x-ratelimit-remaining | Requests left in the current window. |
x-ratelimit-reset | Seconds until the window starts over. |
A 429 also carries retry-after, in seconds. Wait at least that long before the next attempt. Watch x-ratelimit-remaining and slow down background work, such as nightly syncs, before it reaches zero, so replies to customers' messages still have room. See Rate limits.
The error shape
Every failure is JSON under error:
{
"error": {
"code": "dm.window_closed",
"kind": "validation",
"message": "The reply window has closed.",
"hint": "Instagram only allows replies within 24 hours of their last message."
}
}Branch on code. message and hint are written for people and can change. details appears on some errors with extra context, such as the failed checks of a post. See Errors.
What to do with each status
| Status | Meaning | Retry? |
|---|---|---|
401 | The key is missing, unknown, revoked, or expired. | No. Fix the key. |
402 | The plan does not include this, or a plan limit is reached. | No. |
403 | The key's role does not allow this (auth.forbidden). | No. Use a key with a higher role. |
404 | Not found in this workspace. | No. |
409 | Conflicts with the current state, for example a post that is publishing right now. | Only after the state changes. |
422 | The request is not valid, or the platform does not allow it. | No. Change the request. |
424 | The platform refused, and the same request will be refused again. | No. |
429 | A quota or an hourly cap is used up. | Yes, after retry-after. |
503 | The platform is busy or rate limiting eksis. | Yes, with backoff. |
500 | Something failed inside eksis. | Yes, with backoff. |
Codes you will see when building on eksis
| Code | Status | What happened |
|---|---|---|
api.not_on_plan | 402 | A Free key called the REST API. Free keys work with the MCP server only. |
plan.feature_locked | 402 | The plan does not include this feature, for example the DM tools of the MCP server on Free. |
plan.limit_reached | 402 | Every channel slot is in use. |
connect.session_invalid | 404 | The connect session does not exist, expired, or belongs to another workspace. Start a new one. |
connect.needs_credentials | 422 | The platform connects with a password or API key in the app, not through POST /v1/connect. |
dm.window_closed | 422 | The reply window of the conversation has closed. |
dm.cards_unsupported | 422 | Cards were sent on a platform other than Instagram or Facebook. |
dm.too_many_replies | 429 | The workspace sent its hourly DM replies through the API and MCP. |
dm.channel_too_many_replies | 429 | The channel sent its hourly DM replies through the API and MCP, on a workspace whose limits.dmRepliesScope is channel. |
dm.conversation_too_many_replies | 429 | One conversation got 20 replies through the API and MCP this hour. |
api.quota_exceeded | 429 | The workspace used its daily request quota. |
webhook.url_private | 422 | The webhook address points at a private network, localhost, or eksis.io. |
validation.failed | 422 | Some fields are not valid. details names the fields that failed. |
A small helper
One function that sends the key, reads the error, and waits on retry-after keeps the rest of your code short:
export async function eksis(path, { method = 'GET', body, key = process.env.EKSIS_API_KEY } = {}) {
for (let attempt = 1; attempt <= 3; attempt++) {
const res = await fetch(`https://api.eksis.io/v1${path}`, {
method,
headers: {
Authorization: `Bearer ${key}`,
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.ok) return (await res.json()).data;
const { error } = await res.json().catch(() => ({ error: {} }));
const retryAfter = Number(res.headers.get('retry-after'));
const retryable = res.status === 429 || res.status === 503 || res.status === 500;
// Wait for short pauses only. A longer one belongs in your job queue.
const wait = retryAfter || 2 ** attempt;
if (retryable && attempt < 3 && wait <= 30) {
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
continue;
}
throw Object.assign(new Error(error?.message ?? `eksis answered ${res.status}`), {
status: res.status,
code: error?.code,
retryAfter: retryAfter || undefined,
});
}
}A thrown error keeps status, code, and retryAfter, so the caller can decide: hand a closed conversation to a person, put a reply that hit an hourly cap back in the queue for later, or alert you when a key stops working.