Rate limit exceeded

A burst — a backfill loop, a poll with no delay, or several processes sharing one key. Successful responses carry RateLimit and RateLimit-Policy headers showing what is left and when the window resets, so a client never has to guess.

Back off for the seconds given in Retry-After, then continue. To stop hitting it: read the RateLimit header and pace yourself before the wall, poll a generation on an interval rather than in a tight loop, and give separate workloads separate keys so a backfill cannot starve production.

Yes. Wait out Retry-After and send it again — exponential backoff with jitter if you are writing the client yourself.

{
  "type": "https://voicelabs.now/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "A human-readable explanation of this particular occurrence.",
  "instance": "/v1/speech",
  "code": "rate_limit_exceeded"
}

Branch on code, never on status or on the prose in detail: two different problems can share a status, and detail is written for humans and may be reworded. Problems a settings page can resolve also carry settings_url, and a scope failure carries required_scope.