Errors are JSON in the application/problem+json format. Branch on code, which is stable; message is for people and may change.
json
{
"type": "https://api.vmyard.example/problems/insufficient_scope",
"title": "Forbidden",
"status": 403,
"code": "insufficient_scope",
"message": "The API key preset does not allow this action.",
"remediation": "Use an API key whose preset includes this action.",
"correlation_id": "0d9f3b9e-5c1a-4b7e-9e0b-2f4c6a8d1e3f",
"field_errors": {}
}
Field
Meaning
code
The machine-readable error code.
status
The HTTP status, repeated.
message
What went wrong, in words.
remediation
What to do next.
correlation_id
Quote it when you contact support. It is also sent as the x-correlation-id header.
field_errors
Field name → problem, for invalid requests.
retry_after_seconds
When a retry can succeed; also sent as Retry-After.
The SDKs turn problems into typed errors: BadRequestError (400), AuthenticationError (401), PaymentRequiredError (402), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), PayloadTooLargeError (413), UnprocessableEntityError (422), RateLimitError (429), and ServerError (5xx), all subclasses of APIError with code, message, remediation, correlationId, fieldErrors, and retryAfterSeconds (snake_case in Python).
Authentication and access
Status
Code
Meaning and fix
401
unauthenticated
No valid session. Sign in again, or send an API key.
401
invalid_api_key
The key is malformed, unknown, expired, or revoked. Create or rotate a key.
403
csrf_invalid
A browser-session change is missing the x-csrf-token header, or it is wrong. Refresh and retry once.
403
session_required
This route needs a signed-in browser session; API keys can't use it (key management, sign-out, device approval, sign-in methods).
403
insufficient_scope
The key's preset doesn't allow this route. See presets.
403
organization_mismatch
X-Organization-ID doesn't match the API key's organization. Omit it or send the right one.
403
forbidden
Your role can't do this (for example a Viewer starting a machine, or a non-admin reading webhooks).
403
organization_suspended
The organization is suspended, so nothing can create, start, or reach into its machines. Reads, billing, keys, and settings still work. Contact support. See Suspended organizations.
403
recent_auth_required
Linking or removing a sign-in method needs a sign-in within the last 15 minutes. Sign in again.
404
resource_not_found
Nothing with that ID in this organization.
Requests
Status
Code
Meaning and fix
405
method_not_allowed
That HTTP method isn't supported on this path.
409
idempotency_conflict
The Idempotency-Key was already used with a different body. Retry the original body, or use a new key.
413
body_too_large
The request body is too large.
422
invalid_request
A field is missing or invalid. field_errors names it. On GET /v1/machines this includes an unknown sort, order, state, or desired_state, a q over 128 characters, and a cursor made for another sort or order: start again from the first page.
429
rate_limited
Too many attempts (sign-in, email codes, device codes, or more than 5 organizations created in 24 hours). Wait Retry-After seconds.
500
internal_error
Something failed on VMYard's side. Retry later; quote the correlation_id.
503
creates_quiesced
Machine creation is paused on this server. Try again later.
Machines, commands, and files
Status
Code
Meaning and fix
409
machine_deleted
The machine was deleted; its settings can't change.
409
machine_not_created
The machine's create is still pending or didn't succeed, so only a delete is accepted.
409
command_not_started
The background command's start operation hasn't succeeded, so it can't be killed yet. Wait for it.
422
timeout_exceeds_runtime_limit
timeout_ms is above the maximum (600,000). Lower it, or use a background command.
404
file_not_found
No file at that path.
413
file_too_large
The file is over 32 MiB.
422
file_not_text
The file isn't UTF-8. Read it with encoding=base64.
502
guest_action_failed
The machine didn't complete a read. Check the operation and retry.
404
path_not_found
The folder to list or download doesn't exist in the machine. List its parent to see what does.
422
not_a_directory
The path to list or download is a file. Read it with GET /v1/machines/{id}/files instead.
422
path_not_allowed
The path resolves, through a symlink, outside /work, /root, and /home. Browse the symlink's target by its own path.
422
listing_too_large
The listing is too large to return. Ask for a smaller depth or a deeper path.
413
archive_too_large
The folder is over 512 MiB. Download smaller folders, or copy it over SSH.
503
files_unavailable
This server doesn't browse files live. Read and write files by path instead.
409
machine_not_running
The machine must be running for this action. Start it and wait until it is observed running.
409
machine_not_stopped
The machine must be stopped for this action. Stop it and wait until the stop succeeds.
410
output_expired
The command's stored output was removed after the retention period. Its exit code, flags, timing, and sizes remain. See Command history.
Web terminal
Status
Code
Meaning and fix
403
origin_not_allowed
The terminal WebSocket came from a page other than the console's configured address. Open the console from that address.
403
terminal_ticket_invalid
The terminal ticket is missing, expired (30 seconds), already used, or for another machine or session. Mint a new one.
409
terminal_refused
The machine (16) or its host (64) has too many terminals. Close some.
429
terminal_limit_reached
You or the organization have the maximum number of open terminals. Close one first.
503
terminals_unavailable
This deployment has no runtime for terminals.
503
runtime_unavailable
The machine's host can't be reached. Retry shortly.
Opening a terminal also needs a key preset above read_only (insufficient_scope), and a machine that is running (machine_not_running). See Web terminal.
Coding agents
Status
Code
Meaning and fix
403
organization_suspended
The organization is suspended, so agents can't run in its machines. Contact support.
404
conversation_not_found
No conversation with that ID on this machine. List them with GET /v1/machines/{id}/agents/conversations.
409
agent_turn_running
The conversation already has a running turn. Steer it, interrupt it, or wait for it to end.
409
provider_mismatch
A conversation keeps the agent it started with. Leave provider out, or start a new conversation.
409
no_active_turn
Nothing is running to steer or interrupt. Send a prompt instead.
503
agents_unavailable
This deployment or the machine's host can't run agents.
The desktop ticket is missing, expired (30 seconds), already used, or for another machine, session, or a terminal. Mint a new one.
429
desktop_limit_reached
The machine has 4 viewers, or you or the organization have the maximum number of open desktops. Close one first.
503
desktop_unavailable
This deployment has no desktops, or the runtime refused: the machine's image has no desktop, or its host is at a limit.
503
browser_unavailable
The runtime refused browser mode: the machine's image has no browser session, or its host predates browser mode. Open the full desktop instead.
Opening a desktop also needs a key preset above read_only (insufficient_scope), the console's address (origin_not_allowed), and a running machine (machine_not_running). See Desktop.
Machine metrics
Status
Code
Meaning and fix
409
machine_not_running
Live metrics need a running or sleeping machine. Read the one-minute history instead.
503
runtime_unavailable
The machine's host couldn't be reached for live samples. One-minute history still works; retry later.
503
metrics_unavailable
This server has no runtime for live samples. Use the one-minute history. See Machine metrics.
Snapshots and templates
Status
Code
Meaning and fix
409
snapshot_pending
The push is still running, so it can't be deleted yet. Wait for it to settle.
409
snapshot_not_ready
The template's push hasn't finished, or failed. Wait, or use another.
409
snapshot_limit_reached
The machine has 20 live API pushes. Delete one first.
409
template_limit_reached
The organization has 10 live templates. Delete one first.
409
template_name_taken
Another live template in the organization has that name.
422
unknown_template
A create named a template that doesn't exist in the organization.
404
no_snapshot
The machine has no ready snapshot yet. Push one, or wait for the next automatic snapshot.
A fork needs a running machine and a snapshot or template a stopped one (machine_not_running, machine_not_stopped above). See Snapshots and tiers, Templates, and Fork and restore.
Organizations and alerts
Status
Code
Meaning and fix
403
waitlisted
VMYard is invite-only and this account isn't approved yet. Join the waitlist at the problem's waitlist_url; you get an email when you're in. Reads, stopping and deleting machines, billing, and settings still work.
409
waitlist_decision_conflict
(Operators) The waitlist entry can't move that way: only a pending entry can be rejected, and only an approved one revoked.
409
already_member
The invited person, or you, already belong to the organization.
409
invitation_closed
The invitation was already accepted, revoked, or has expired. Ask for a new one.
403
invitation_email_mismatch
None of your sign-in addresses is the invited one. Sign in with the invited address, or link it first.
409
last_owner
The organization's only owner can't be removed or demoted. Transfer ownership first.
409
subscription_active
An organization with a renewing plan can't be deleted. Cancel the plan and wait for its period to end.
503
invitations_unavailable
This deployment can't send invitations: email or the console's address (ui_base_url) isn't configured.
409
organization_name_taken
You already created an organization with that name (names are unique per creator, ignoring case).
400
invalid_unsubscribe_token
The unsubscribe link is damaged, or the server's session secret was rotated since it was sent. Change the alert from the console's Alerts page instead. See Email alerts.
Ports and SSH
Status
Code
Meaning and fix
503
ingress_unavailable
This deployment has no edge configured, so ports and SSH aren't available.
409
port_limit_reached
The machine already has 16 exposed ports. Close one first.
404
port_not_exposed
Expose the port before asking for a token.
Billing and limits
Status
Code
Meaning and fix
402
billing_required
The spendable balance is at or below the minimum balance. Buy credits or a plan.
402
spend_cap_reached
This month's credit spend reached the spend cap. Raise or remove it, or wait for next month.
402
card_verification_required
The deployment asks trials to verify a card before machines start. An Owner or Billing member starts a card check; the card is not charged.
403
trial_machine_class_not_allowed
Trials can use only small and default. Choose a smaller size, or buy credits or a plan.
409
plan_not_priced
The plan has no current price. Choose another from /v1/plans.
429
limit_reached
A concurrency or start-rate limit. field_errors.limit says which; start windows send Retry-After.
409
insufficient_credit
(Operators) A claw-back is larger than the organization's credit balance.
409
billing_customer_missing
The payment portal needs a completed purchase first.
409
payment_method_missing
Automatic refill needs a default payment method. Add one in the payment portal.
409
subscription_missing
There is no paid plan subscription to cancel or resume.
502
payment_provider_error
The payment provider failed. Retry later.
503
billing_unavailable
Online payments aren't configured on this deployment.
400
invalid_signature
(Stripe events endpoint) The Stripe-Signature didn't verify.
400
invalid_event
(Stripe events endpoint) The event couldn't be read.
The organization already has 10 endpoints. Delete one first.
503
webhooks_unavailable
This deployment has no keys to encrypt signing secrets, so endpoints can't be created and secrets can't be rotated. Secrets are never stored in plaintext.
Sign-in
These come back from the email and linking routes:
Status
Code
Meaning and fix
400
invalid_code
The email code is wrong, expired, used, or replaced by a newer one. Request a new code.
404
unsupported_provider
That sign-in method isn't configured.
409
identity_in_use
That identity already belongs to another user.
409
last_login_method
You can't remove your only sign-in method. Link another first.
503
email_unavailable
The email couldn't be sent. Retry later.
503
oidc_unavailable
The sign-in provider couldn't be reached.
401
oidc_failed
The provider's answer couldn't be verified. Start again.
Browser sign-in redirects to /sign-in?error=<code> with one of access_denied, identity_in_use, oidc_failed, oidc_unavailable, session_expired, or unsupported_provider. See Sign-in methods.
Device sign-in
POST /v1/auth/device/token uses the OAuth error shape, 400 {"error", "error_description"}, not problem details: authorization_pending, slow_down, access_denied, expired_token, invalid_grant, invalid_request, and unsupported_grant_type. See CLI device login.
Operation error codes
An operation that ends failed, uncertain, or correlation_miss has an error_code. These are the ones you are most likely to see:
error_code
Meaning
exec_nonzero
The command exited with a non-zero code. exec_result has the output.
exec_timed_out
The command ran past timeout_ms.
exec_cancelled
The command was cancelled.
exec_no_exit_status
The command ended without an exit status.
setup_prerequisite_failed
The create (or the environment apply it waits for) failed, so the setup script never ran.
Installing the machine's environment failed. The machine keeps running.
environment_prerequisite_failed
The create failed, so the environment was never installed.
invalid_transition
The machine's observed state doesn't allow this action.
fleet_error
The machine's host refused or failed the request, for example closing a port that isn't exposed, or an internet access change on a host without guest networking or with internet access turned off. Nothing changed.
restart_unsupported
The machine's host can't restart its machines yet, so the restart never started. Nothing changed and the machine kept running; stop and start it instead.
network_mismatch
The host answered an internet access change with a different policy than the one requested, so VMYard did not report success. Read the machine's network before retrying.
runtime_timeout, runtime_transport
The host didn't answer in time or couldn't be reached.