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:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | When 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" }),
});