API
Handle API errors
Classify device and app API failures and correlate requests without parsing human-readable messages.
Error contract
Device and app API errors include a top-level machine-readable code. Existing
detail, message, error, and validation errors fields remain available;
their shape depends on the endpoint. Branch on code, not message text.
{
"detail": "Device not connected",
"code": "device_not_connected"
}This contract covers /api/v1/execution/start_device, device-proxy routes,
device-session routes, streaming worker-connection routes, and /api/v1/apps
routes, including app creation, build upload/finalization, and remote-build runner
availability. The legacy /api/v1/builds routes use the same contract.
The partner connections API retains its separate nested error.code envelope.
Do not treat a product error as a partner connection error.
Request correlation
Send a UUID in X-Request-ID to correlate your request with Revyl diagnostics.
Revyl echoes its canonical UUID spelling on success and error responses. If the
header is missing or invalid, Revyl generates a UUID. Record the returned header
when reporting a failure. A request ID is not an idempotency key and does not
make a repeated mutation safe.
Codes and recovery
| Code | Meaning and action |
|---|---|
device_not_connected | The worker reports that its device is not connected. Re-check session readiness before sending another action. |
upload_expired | The multipart upload no longer exists. Discard its saved upload state and start a new upload. |
worker_gone | The session's worker route is missing or the worker cannot be reached. Re-check the authorized session state; do not assume a mutation was never applied. |
app_exists | An active app with that name already exists in your organization. The 409 includes existing_app_id; use that ID instead of creating another app. |
no_runner | Legacy. Build submissions no longer return it: a build queues until a runner takes it. Treat it as temporarily_unavailable if an older response has it. |
credits_exhausted | Build admission was denied by the compute-credit gate. Check the payer's credits before retrying; see Billing refusals. |
billing_denied | Device admission was denied by the billing gate. Resolve the payer's entitlement before retrying; see Billing refusals. |
billing_unavailable | Billing verification could not complete. Retry only when the requested operation is safe to repeat. |
authentication_required | Provide valid credentials. |
access_denied | The authenticated caller cannot perform this operation. |
not_found | The resource is missing or inaccessible to this caller. The response does not distinguish other organizations' resources. |
invalid_request | Correct the request, including any validation errors, before retrying. |
conflict | Resolve the conflicting state before repeating the operation. |
rate_limited | Respect Retry-After when present. |
request_timeout | The request timed out. Read the current state before repeating a mutation. |
temporarily_unavailable | A dependency is temporarily unavailable; preserve the request ID for diagnostics. |
worker_error | The worker request failed without a more specific classification. |
internal_error | Revyl could not complete the request. Preserve the request ID; do not automatically replay a mutation. |
Billing refusals
A billing_denied or credits_exhausted refusal of your organization's own
work can also carry billing_url, a Billing settings link, and
billing_action, the one action that resumes work: add_card, top_up,
update_card, raise_limit, or request_access (ask an owner or admin to
raise the cap). Both fields are absent when Revyl cannot tell why the payer was
refused, and when a partner pays for the work. Show detail and the link; do
not build the URL yourself. detail is two lines, the reason and then the next
step with its link; requests from CI get both on one line.
When a Free organization is offered Pro (add_card), the refusal can also
carry upgrade_benefits: concurrent_devices_now, the devices it can run
at once today, and concurrent_devices_payg, the devices it can run at once
on Pro. It is absent when Revyl cannot read the plans.
A start that finds every device busy is not refused. It waits for a free
device, and its 200 response can carry queue_notice: devices, the number
the organization runs at once; message; and, when a step would let more run
at once, action (add_card, request_access, or contact_sales) with its
billing_url. contact_sales is an organization on Pro at its device limit,
and its billing_url is where to talk to Revyl about more.
A Mac computer does not wait for a free device. Its start is refused with
429 and detail: "computer_limit". When a step would let more run at
once, the body also carries offer: action (add_card on Free, or
request_access for a member; contact_sales on Pro), message, and
billing_url.
{
"detail": "Free minutes used up for this month.\nUpgrade to Pro to keep running, with 10 devices at once instead of 2 ($20 credit, charged when you add a card): https://app.revyl.ai/settings/billing?add_card=1&organization_id=<org-id>",
"code": "billing_denied",
"billing_url": "https://app.revyl.ai/settings/billing?add_card=1&organization_id=<org-id>",
"billing_action": "add_card",
"upgrade_benefits": { "concurrent_devices_now": 2, "concurrent_devices_payg": 10 }
}Existing feature-specific codes are preserved. Handle unknown codes as errors using the HTTP status and retain their request IDs; clients should not require a closed list of codes.
Retry-After, when supplied, is a delay in seconds. It is not a promise that
capacity will be available afterwards. No retry delay is invented when Revyl
does not know one.
An ordinary full device pool can return 200 with an initializing or queued
session. Likewise, runner availability can return 200 with available: false. These are status results, not error responses; no slots_full error is
implied.
Recover an existing app
For an app-name conflict, the response retains its existing human-readable detail and adds the organization-scoped ID:
{
"detail": "An app named \"My app\" already exists in this organization.",
"code": "app_exists",
"existing_app_id": "00000000-0000-0000-0000-000000000123"
}The ID comes only from the caller's organization and excludes deleted apps.