Handle Dosya API rate limits
Read Dosya rate-limit headers, honor Retry-After, add bounded jitter, and retry safely without turning a temporary 429 into a tight request loop.
Last reviewed
Dosya enforces more than one limit. General authenticated and upload traffic is limited to 300 requests per minute per user, listing traffic to 600 per minute, and authenticated IP traffic to 600 per minute outside the desktop-sync exception. An API key may also have its own requests-per-minute allowance.

Before you start
- Make the caller preserve response status and headers; a JSON parser alone loses the retry signal.
- Decide whether the request is safe to replay. Reads are usually safe; mutations need a route-specific receipt or idempotency contract.
- Keep concurrency below the documented limit instead of relying on retries as flow control.
Steps
- Inspect every response for
X-RateLimit-Limit,X-RateLimit-Remaining, andX-RateLimit-Reset. The general limiter also includes those headers on successful requests. - When status is 429, read
Retry-Afterbefore parsing the body. A per-key refusal can sayThis API key has exceeded its requests-per-minute limitand is only guaranteed to includeRetry-After. - Pause for the server delay, then add a small random jitter so parallel workers do not wake together. Cap a malformed or excessive delay according to your job deadline.
- Retry a read or an idempotent upload after waiting. For an uncertain move, rename, trash, or other mutation, verify the remote state instead of replaying it automatically.
- Limit the retry count. Dosya CLI uses at most three retries, a fallback sequence of 1, 3, and 8 seconds, and caps a valid
Retry-Aftervalue at 60 seconds. - Record the route, status, attempt number, and wait duration without logging credentials. Reduce concurrency when 429s recur after a complete reset window.

Expected result
The client waits instead of spinning, succeeds after capacity returns, and stops after its bounded retry budget. Automation distinguishes a key-level allowance from the broader user or IP limiter without assuming identical headers.
Troubleshooting
Retry-After is absent. Use a conservative exponential delay with jitter; the CLI’s fallback is 1, 3, then 8 seconds.
A mutation timed out before its status arrived. Read the resource or receipt endpoint. Only replay when that operation documents idempotency.
429 continues after the reset. Lower concurrency and inspect the API key’s configured requests-per-minute allowance. A new key does not remove user- or IP-level protection.
Related guides
Was this helpful?
Loading helpfulness results…
Voting saves a necessary ballot cookie for up to 180 days so you can change your answer.
Questions and replies
Ask about the steps in this guide. Questions are reviewed before publication.
Keep account details, credentials and private files out of public questions. Use private support for those.
Loading questions…
Sign in to your Dosya account to ask a question.