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.

Four workflow panels show inspecting rate-limit headers, reading Retry-After, retrying only a safe operation, and capping three waits at 60 seconds.
The diagram covers inspecting rate-limit headers, reading Retry-After, retrying only a safe operation, and capping three waits at 60 seconds. Open full-size screenshot.

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

  1. Inspect every response for X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. The general limiter also includes those headers on successful requests.
  2. When status is 429, read Retry-After before parsing the body. A per-key refusal can say This API key has exceeded its requests-per-minute limit and is only guaranteed to include Retry-After.
  3. 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.
  4. 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.
  5. 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-After value at 60 seconds.
  6. Record the route, status, attempt number, and wait duration without logging credentials. Reduce concurrency when 429s recur after a complete reset window.
Dosya developer overview with API and SDK entry points for handle dosya api rate limits.
The developer overview supplies the API and SDK entry points referenced by “Handle Dosya API rate limits”. Open full-size screenshot.

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.

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.

    Check the outcome before you retry

    Use these shared checks when a task needs a second look.