Rate limits

Each API key can make a set number of requests per minute. Every response tells you where you stand.

The limit

  • Limits are per API key, counted in fixed 60 second windows.
  • The default is 120 requests per minute per key. A key may have its own limit.
  • One request can carry up to 1000 SMS recipients, so batch recipients into one request rather than sending one request per number.

Rate limit headers

Every /v1 response carries:

HeaderMeaning
X-RateLimit-LimitRequests allowed in the current window.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetWhen the window resets, in unix seconds.

When you go over

You get 429 RATE_LIMITED, with a Retry-After header and retry_after in the body, both in seconds. Nothing was done, so wait that long and send the same request again.

Response
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793528160

{ "error": "Rate limit exceeded", "code": "RATE_LIMITED", "retry_after": 17 }

Retry example

async function kpododoRequest(path, init = {}, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const response = await fetch(`https://api.kpododo.com${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${process.env.KPODODO_API_KEY}`,
        "Content-Type": "application/json",
        ...init.headers,
      },
    });

    if (response.status !== 429) return response;

    // Wait as long as the API asks, plus a little jitter so many workers
    // do not all retry in the same second.
    const retryAfterSeconds = Number(response.headers.get("Retry-After")) || 1;
    const jitterMs = Math.random() * 500;
    await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000 + jitterMs));
  }
  throw new Error("Still rate limited after several attempts");
}

// A POST keeps the same Idempotency-Key across these retries because the
// headers object is reused.
const response = await kpododoRequest("/v1/sms", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ from: "MyShop", to: ["0244000111"], text: "Hello" }),
});