Rate limits and retries

What is the API rate limit?

120 requests a minute per API key. The count starts with your first request and resets one minute later.

If you go over, you get 429 with a Retry-After header saying how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 23

{ "error": "Too many requests: the limit is 120 a minute per key" }

How should I handle 429?

Wait the number of seconds in Retry-After, then try again. For example, in Node.js:

async function callKiliChat(path, options = {}, attempt = 1) {
  const res = await fetch(`https://app.kilichat.com/api/v1${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${process.env.KILICHAT_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });
  if (res.status === 429 && attempt < 5) {
    const wait = Number(res.headers.get("Retry-After") ?? 60);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return callKiliChat(path, options, attempt + 1);
  }
  return res;
}

Sending to many people?

120 a minute is plenty for messages triggered by events, like order updates. To message hundreds or thousands of people at once, use a broadcast in KiliChat instead of looping over the API. Or add contacts with a tag through the API and let a sequence send the messages.

Should I retry other errors?

Status	Retry?
400, 401, 404, 422	No. Fix the request first; it will fail the same way again.
429	Yes, after Retry-After seconds.
500	Yes, a few times with a growing wait (for example 5 s, 30 s, 2 min).
502 (message failed)	Depends on Meta's reason in error. See Meta error codes. Don't retry "undeliverable" or opt-out errors.

Do Meta's limits apply to API messages?

Yes. Messages you send through the API count towards your number's Meta messaging limit, like any other. See Limits and pacing.

How are webhook deliveries retried?

A delivery succeeds when your endpoint answers with a 2xx status within 10 seconds. Anything else counts as a failure: another status, a timeout, a redirect or no connection.

When a delivery fails, KiliChat tries again after 1, 5, 30, 120 and 360 minutes. That's six tries over about 8½ hours. After the last one, the delivery is marked Failed.

You can send a failed delivery again by hand: click Deliveries on the webhook, then Retry on the failed row. It goes back in the queue and gets a fresh set of retries.

A Send test (ping) is tried once only and isn't retried.

When does a webhook get turned off?

After 50 failures in a row, KiliChat turns the webhook off so it stops trying. The card shows Off and "Turned off after 50 failures in a row. Fix the endpoint, then turn it back on." The KiliChat team is also alerted.

To start again:

1. Fix your endpoint.
2. Click Send test to check it answers.
3. Click Turn on. The failure count resets to zero.

Deliveries still waiting to be retried carry on once the webhook is back on.

How long is delivery history kept?

About 30 days. The Deliveries window shows the latest 50.

Can deliveries arrive twice?

Rarely, yes, for example if your endpoint did the work but answered too slowly, so KiliChat retried. The X-KiliChat-Delivery header (and body id) is the same on every retry of the same delivery. Store the ids you've handled and skip repeats.