Rate limits
Build clients that retry politely and avoid duplicate work.
BoringKit uses bounded request, job, and file-processing limits to keep utility work predictable. Treat rate-limit responses as backpressure and retry with the same idempotency key for the same mutation.
Client rules
Discover first
Read /tools before creating jobs so your client knows accepted types, size limits, batch limits, and whether /jobs is supported.
Use idempotency
Send Idempotency-Key on POST /jobs, cancellation retries, and other mutating requests that may be repeated by your network stack.
Back off
On 429 or temporary 5xx responses, wait before retrying and apply exponential backoff with jitter.
Limit concurrency
Keep concurrent uploads and running jobs bounded per account. Poll existing jobs instead of creating duplicates.
Respect file windows
Upload intents and download intents expire quickly. Request a new intent only when the previous one expired before use.
Retry response pattern
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after the indicated delay."
}
}What not to retry unchanged
- Validation failures such as unsupported content type, oversized input, or malformed JSON.
- Safety rejections such as private network URLs, unsupported protocols, unsafe redirects, or empty files.
- Plan or authorization errors such as missing scopes, revoked keys, or plan upgrade requirements.
- Expired output responses. Re-run the job if retention has ended.