API errors

Rate limit exceeded

You have sent too many requests in the current window. Wait for the time in Retry-After, then try again.

429503application/problem+json

What it means

The API applies per-second rate limits. When you exceed yours, requests are refused with 429 until the window resets; the rate-limit response headers tell you what your limits are.

A 429 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 present on other responses too, so you can watch your remaining budget before you ever hit the limit.

This type can also arrive with status 503 when an upstream carrier is rate limiting Firsty itself. It carries Retry-After as well, and the same handling applies.

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."
}

How to handle it

Wait at least Retry-After seconds before retrying, and add jitter so a fleet of workers does not retry in lockstep.
Back off exponentially if the limit keeps tripping. Sustained 429s mean your steady-state rate is above your limit, not that you are unlucky.
Cache OAuth tokens for their 24 hour lifetime instead of requesting one per call. Token churn is a common source of avoidable requests.
Send X-Idempotency-Key on POST and PATCH requests so a retry can never duplicate the operation.

Rate limits guide Errors reference

What it means

How to handle it

Related