Your request is accepted, kept in your own queue, processed on Revoye Cloud or on your device with Revoye Desk, and the response comes back to your app. Which of the two processes it depends on your plan and on the channel you send. Your code calls the same API either way.

Knowing the steps is what lets you design an integration that works with the queue instead of against it.

The life of a request

your app
  → POST /v1/completions          accepted, with a job id
  → plan check                    active plan, channel included, allowance left
  → your queue                    kept safely until it can be processed
  → Revoye Cloud or Revoye Desk   chosen by your plan and the channel field
  → the response
  → your waiting request, GET /v1/completions/{id}, or your callback_url

1. Accepted means kept

Revoye records the request before it does anything else, and returns its id. From that moment:

A dropped connection does not lose it. Fetch it at GET /v1/completions/{id}.
A Revoye deploy does not lose it.
Revoye Desk being offline does not lose it.

This is the most useful property to design around. Your integration's job is to record the id, not to hold a connection open.

2. The plan check comes first

Before anything is queued, Revoye checks the request against your plan. Each of these is refused immediately, so nothing waits in a queue it can never leave:

Check	If it fails
You have an active plan	`403 SUBSCRIPTION_INACTIVE`
The `channel` you named is in your plan	`403 CHANNEL_NOT_ENTITLED`
The channel's monthly token allowance has room for the request	`429 QUOTA_EXCEEDED`, with `details.resets_at`

3. Revoye Cloud or Revoye Desk

Your plan	With `channel: "auto"` (the default)
Revoye Cloud only	Processed on Revoye Cloud
Revoye Desk only	Processed by Revoye Desk on your device
Both	Your preferred channel first, set on the Routing page of the dashboard

With both, fallback is on by default. If your preferred channel cannot process the request right now, it goes to the other one straight away. If it is queued on the first channel for longer than your fallback delay — 30 seconds unless you change it — it moves to the other channel once. A request is only ever on one channel at a time. If one channel's monthly allowance is used up, auto uses the other.

Naming channel: "cloud" or channel: "desk" is a constraint: the request is processed there or refused, and never quietly moved. Continuing an earlier conversation fixes the channel the same way.

4. Waiting in the queue

On Revoye Cloud, your plan sets how many of your requests are processed at the same time. The rest wait in your queue, highest priority first, and start as soon as earlier ones finish.

On Revoye Desk, requests are processed while Revoye Desk is running and online on one of your devices. If it is not online anywhere:

Your request said	What happens
`wait: true`	The request waits in your queue, and is processed when Revoye Desk is back
`wait: false` with a `callback_url`	Accepted and queued. The webhook fires when it is processed
`wait: false`, no `callback_url`	`503 NO_DEVICE_ONLINE` straight away — unless a fallback to Revoye Cloud is scheduled

For anything unattended, the second row is the one you want.

5. Processing, timeouts and retries

Most responses arrive in 3 to 90 seconds, depending on the length of the request and of the response. The response is delivered complete — there is no streaming.

Two clocks protect the request, not the connection:

	Field	Default	Range	Covers
Per attempt	`timeout_ms`	180 000	5 000–600 000	One attempt at processing
Whole request	`deadline_ms`	900 000	10 000–3 600 000	Every attempt together

If an attempt fails or times out, Revoye tries again, up to a limited number of attempts. When the deadline passes, the request stops.

wait: true holds your HTTP connection for at most min(deadline_ms, 600000). If that expires you get 504 JOB_TIMEOUT with the job id, and the request keeps going. The timeout is your patience, not the request's.

6. The response comes back with its history

Every finished request tells you what happened, not just what it produced: channel, attempts, queue_ms (how long it waited before processing first started) and run_ms. When something is slow, those fields say whether it was the queue or the processing.

The tokens in your request and its response count toward that channel's monthly allowance when the request succeeds. A request that fails is not counted.

What this means for your integration

Store the job id. It is the only thing you cannot recover.
Set a long client timeout, or do not wait at all. A 30-second default will abandon healthy requests.
Use Idempotency-Key. Retrying safely.
Treat NO_DEVICE_ONLINE and NO_AGENT_AVAILABLE as capacity, not failure. Back off and retry.
Keep channel: "auto" on a plan with both channels, so fallback can do its job.

How a Revoye API request is processed