Design for a queue whose responses arrive in seconds to about a minute. Every recommendation here follows from that. An integration that respects it runs unattended for months; one that fights it feels unreliable.

1. Match the workload to the tool

Good fit	Poor fit
Content generation: descriptions, summaries, rewrites, replies	Real-time chat with someone watching each word appear
Background enrichment, classification, translation	Sub-second interactive features
Automation steps and scheduled jobs	Agent-style coding tools that make many calls a minute
Everyday app features and light coding help	Anything with a deadline in seconds

If a person is staring at a cursor waiting, design the feature so the response can arrive a little later — or choose a different tool for it.

2. Prefer asynchronous submission

wait: true is convenient for a script. For anything running unattended, submit with wait: false and a callback_url. It removes your dependency on a connection surviving a minute, it removes the client-timeout bug class entirely, and it turns Revoye Desk being offline from an error into a delay.

3. Always send an idempotency key

Derive it from your own work item's identity, not from a fresh UUID inside the retry loop. Retrying safely.

4. Let Revoye choose

Omit provider (or use model: "revoye/auto") and keep channel: "auto":

Availability. If one model is busy, Revoye uses another that your plan includes.
Fallback. On a plan with both channels, a request can move between Revoye Cloud and Revoye Desk only when you did not pin it.
Budget. When one channel's monthly allowance is used up, auto keeps working on the other.

Pin a model or a channel only when the response genuinely depends on it.

5. Set timeouts deliberately

Request shape	`timeout_ms`
Short instruction, short response	Default (180 000) is generous
Long document, long response	300 000–600 000

Set deadline_ms to the point at which the response stops being useful to you. That is what stops a retry chain outliving its own purpose.

6. Ask for the format you need

The response is written for a reader unless you say otherwise. Two consequences:

Ask for the output format explicitly. "Reply with JSON only, no explanation." "Return exactly five bullet points."
Parse defensively. Strip code fences, tolerate a short preamble, and validate before you trust. Treating the response as guaranteed-shaped JSON will break.

7. Instrument the fields the response gives you

channel, attempts, queue_ms, run_ms. Log them on every request and you can answer, without guessing:

Are requests waiting (queue_ms high) or taking long to process (run_ms high)?
Does one channel retry more than the other (attempts by channel)?
Is the wait growing over a week?

8. Monitor from `/v1/status`, on a schedule

Once a minute is plenty. Alert on a channel's available: false sustained past your tolerance, on queue.oldest_queued_at older than your deadline, and on quota.*.used approaching limit. Do not poll it per request — that is how you hit the request rate limit.

9. With Revoye Desk, keep your device ready

Keep the device awake when it is meant to be working. Sleep settings are the commonest cause of "Revoye stopped working" on Revoye Desk.
Keep Revoye Desk running and up to date. Requests for Revoye Desk wait while it is closed.
Stay signed in to your AI account in Revoye Desk. It tells you when a sign-in needs attention.
Consider both channels. On a plan with Revoye Cloud too, requests keep flowing while your device is off.

10. Keys: narrow, separate, rotatable

One key per deployment, scoped to what that deployment does, in a secret manager. Write-only for a client, read-only for a monitor. Authentication.

Best practices