Rate limits

Over any limit, the API answers 429 with the code rate_limited:

{
  "error": "Too many requests with this API key. Try again in 23 seconds.",
  "code": "rate_limited"
}

Requests per key

Each key gets 60 requests in a fixed one-minute window. The window starts with your first request, and the count resets when it ends. The Retry-After header says how many seconds are left.

Two keys in the same workspace each get their own 60. Use one key per integration, so a busy sync doesn't starve your other tools.

Writing at once

Postel writes up to 3 posts at a time per workspace through the API. Writing a post takes 5 to 30 seconds, and a take 10 to 40. A fourth request while three are running gets 429 with Retry-After: 30. A slot frees up as soon as a request finishes.

If you write in bulk, run at most three requests in parallel and queue the rest.

Viral search

GET /v1/viral/posts allows 30 searches a minute per workspace. Postel also caps viral search across all users, so you can get 429 with the message "Viral search is busy" below your own limit. These responses have no Retry-After header; the error message says how many seconds to wait.

Handling 429

async function withRetry(request, attempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const res = await request();
    if (res.status !== 429 || attempt === attempts) return res;
    const seconds = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

const res = await withRetry(() =>
  fetch("https://www.postel.app/api/v1/posts?limit=100", {
    headers: { Authorization: `Bearer ${process.env.POSTEL_API_KEY}` },
  }),
);

When you retry a POST that creates something, send the same Idempotency-Key each time.