The API enforces rate limits at two levels: a per-key burst limit and a per-account monthly quota. The HTTP response always includes the relevant headers.

Headers

| Header | Meaning | | ------ | ------- | | X-RateLimit-Limit | Allowed requests in the current window | | X-RateLimit-Remaining | Requests remaining | | X-RateLimit-Reset | Seconds until the window resets | | Retry-After | Seconds to wait before retrying (on 429) |

Idempotency

Pass an Idempotency-Key header on POST requests to make retries safe:

const poster = await client.posters.generate(
  { location: { lat: 52.52, lng: 13.405 } },
  { idempotencyKey: 'order-1234-attempt-1' }
);

Error envelope

{
  "error": "rate_limited",
  "message": "You exceeded 60 requests per minute. Retry in 17s.",
  "request_id": "req_abc123"
}

The request_id is required when contacting support — it lets us trace the exact request across the stack.

Recommended retry strategy

1. Honor Retry-After exactly.
2. Apply exponential backoff with full jitter on 5xx errors.
3. Stop retrying after 5 attempts and surface the error to the user.