rate_limited

What it means

Too many requests. A key may make 120 requests a minute. The RateLimit header says how many are left, and Retry-After how long to wait.

Common causes

• A loop sending requests without waiting.
• Several programs sharing one key.

What to do

Wait the number of seconds in retry_after, then try again.

Can I retry it?

Yes, after waiting. Wait the seconds in retry_after (or the Retry-After header) when the answer has them, otherwise back off from a second or two. With the same Idempotency-Key, a retried send never sends twice.

What the answer looks like

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Wait 12 seconds.",
    "hint": "Wait the number of seconds in `retry_after`, then try again.",
    "doc_url": "https://usebluebot.com/docs/errors/rate_limited",
    "retry_after": 12,
    "request_id": "req_1Hq2LxW9cVbN3mKpRtYs0a"
  }
}

Branch on code, which never changes. message and hint are written for people and may be reworded. Quote request_id when you write to support.

Related

• Errors: the envelope and every code
• Idempotency: retrying without sending twice
• Limits: every cap and what happens when you reach it