API errors

rate_limit_exceeded

Too many requests in the current window. Wait for the time in `Retry-After`, then try again.

429application/problem+json

What it means

The response carries RateLimit and RateLimit-Policy headers describing the window and what is left of it, and Retry-After with the number of seconds to wait. The RateLimit headers are on other responses too, so you can watch the remaining budget before reaching the limit.

429 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests. Please try again later.",
  "code": "rate_limit_exceeded"
}

How to handle it

Wait at least Retry-After seconds before retrying, and add jitter so parallel workers do not retry in lockstep.
Back off exponentially if the limit keeps tripping; your steady-state rate is above the limit.
Cache tokens for their lifetime instead of requesting one per call.

Errors reference