The API reference moved here from eksis.io/developers.

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

QuotaCountedWhen it runs out
Requests a day, REST and MCP togetherPer workspace429 with api.quota_exceeded
DM replies an hour through the API and MCPPer workspace, or per channel when limits.dmRepliesScope is channel429 with dm.too_many_replies or dm.channel_too_many_replies
DM replies an hour into one conversationPer conversation, 20 on every plan429 with dm.conversation_too_many_replies
ChannelsPer workspace402 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:

HeaderValue
x-ratelimit-limitThe daily request quota of the workspace.
x-ratelimit-remainingRequests left in the current window.
x-ratelimit-resetSeconds 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

StatusMeaningRetry?
401The key is missing, unknown, revoked, or expired.No. Fix the key.
402The plan does not include this, or a plan limit is reached.No.
403The key's role does not allow this (auth.forbidden).No. Use a key with a higher role.
404Not found in this workspace.No.
409Conflicts with the current state, for example a post that is publishing right now.Only after the state changes.
422The request is not valid, or the platform does not allow it.No. Change the request.
424The platform refused, and the same request will be refused again.No.
429A quota or an hourly cap is used up.Yes, after retry-after.
503The platform is busy or rate limiting eksis.Yes, with backoff.
500Something failed inside eksis.Yes, with backoff.

Codes you will see when building on eksis

CodeStatusWhat happened
api.not_on_plan402A Free key called the REST API. Free keys work with the MCP server only.
plan.feature_locked402The plan does not include this feature, for example the DM tools of the MCP server on Free.
plan.limit_reached402Every channel slot is in use.
connect.session_invalid404The connect session does not exist, expired, or belongs to another workspace. Start a new one.
connect.needs_credentials422The platform connects with a password or API key in the app, not through POST /v1/connect.
dm.window_closed422The reply window of the conversation has closed.
dm.cards_unsupported422Cards were sent on a platform other than Instagram or Facebook.
dm.too_many_replies429The workspace sent its hourly DM replies through the API and MCP.
dm.channel_too_many_replies429The channel sent its hourly DM replies through the API and MCP, on a workspace whose limits.dmRepliesScope is channel.
dm.conversation_too_many_replies429One conversation got 20 replies through the API and MCP this hour.
api.quota_exceeded429The workspace used its daily request quota.
webhook.url_private422The webhook address points at a private network, localhost, or eksis.io.
validation.failed422Some 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.

On this page