Rate limits
A rate limit is a cap on how much work a client may ask for in a period of time. When a limit is reached, the API answers 429 Too Many Requests instead of doing the work, and you try again later. This page says which limits the IBEE API applies, and how to retry without doing a write twice.
Which limits apply
Because no request rate is published, don’t build on an assumed number. Write your client so that it slows down when it sees 429, and contact support before you run large batch jobs in production.
When to use a retry
A retry helps only when the problem is temporary. For everything else, the same request gets the same answer.
How it works
- A request reaches a limit, or a service it depends on is briefly unavailable.
- The API answers
429(limit) or503(dependency unavailable) and does nothing else. A503from the gateway’s check carries anerrorcode such asworkspace_verification_unavailableorbilling_admission_unavailable; the request never reached the product. - If the response has a
Retry-Afterheader, it says how many seconds to wait. - Your client waits, then sends the same request again, if it is safe to repeat.
Before you begin
- Know which of your requests are safe to repeat: reads (
GET) always are. A write is safe to repeat only when it carries the same idempotency key as the first attempt: a unique string, sent in theX-Idempotency-Keyheader, that lets the API recognise a repeated request. The VM writes that take one are listed in Idempotency. - Use a client that can read the response status and headers.
curl -Dsaves headers to a file; the SDKs expose them on every error. - If you use an SDK, the CLI or Terraform, retries are already built in. See Retry settings in the IBEE tools.
Handle a 429 or 503
Check the status and the body
Retry only 429, 503 and 409 idempotency_in_progress. Every other error needs a change to the request, the token or your account first; retrying the same request gets the same answer.
Don’t retry a billing answer
If the body has a billing_reason, an admission_context_id, or an error code containing billing, admission, catalog or quote, Billing is involved. A 503 such as billing_admission_unavailable can be retried later; a 402 billing_denied cannot until you fix the cause.
Wait
Wait the number of seconds in Retry-After if it is there. Otherwise wait 1 second, then 2, then 4: double the wait each time, and add a little randomness (jitter) so many clients don’t retry at the same moment.
This script reads the list of compute sites and retries 429 and 503 up to 3 times, honouring Retry-After when it is a number of seconds:
Retry settings in the IBEE tools
The SDKs, the CLI and the Terraform provider retry for you. Their defaults:
The Python SDK, the CLI and the Terraform provider never retry an answer that carries a billing or admission code. The TypeScript SDK doesn’t check for those codes, so it can retry a 503 such as billing_admission_unavailable on a write with an idempotency key. No tool retries a VM create, or a read of a secret identity’s login details, because each read issues a new secret ID. Set max_retries (Python) or maxRetries (TypeScript) to change the number of retries; 0 turns retries off.
Keep your request count down
- Read sites, plans and images once per run and reuse the IDs, instead of before every create.
- Ask for bigger pages (the list’s maximum
limit) rather than many small ones. - Poll asynchronous work at a steady pace, every 2 to 5 seconds. Terraform checks an operation every 2 seconds; the SDKs and the CLI leave polling to you. See Asynchronous operations.
- Don’t run the same create from several processes; give each action one owner and one idempotency key.
Troubleshooting
Related pages
- API overview: every status and error code
- Asynchronous operations: polling without wasting requests
- Lists and paging: page sizes per list
- SDKs, CLI and Terraform
