Errors
The InstaVM API reports an error with an HTTP status code and a JSON body. This page shows the body shapes, lists the status codes the API returns, and says which requests you can safely retry.
curl -i https://api.instavm.io/v1/vms
HTTP/1.1 401 Unauthorized
Content-Type: application/json
x-request-id: 44322c6b-5b7b-4248-b608-c339322a21f1
{"detail":"No authentication provided. Use either Bearer token or X-API-Key header."}
Error body
Every JSON error has one field, detail. Its type depends on the error, so check the type before you read it:
detail is | When |
|---|---|
| a string | Most errors. Example: {"detail": "VM not found"} |
| a list of objects | Request validation failed (422). See Validation errors. |
| an object | Errors that carry extra fields, usually a machine-readable code. See Error codes. |
The text of a detail message can change. Branch on the status code and, where present, on detail.code.
Validation errors
When a body field, query parameter or path parameter does not match the schema, the API answers 422 and detail lists every problem. loc is the path to the field:
curl -X POST https://api.instavm.io/v1/ssh-keys \
-H "X-API-Key: $INSTAVM_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
{
"detail": [
{
"type": "missing",
"loc": ["body", "public_key"],
"msg": "Field required",
"input": {}
}
]
}
The API checks your API key before it validates the request, so a request with a missing or invalid key gets 401 even when its body is also invalid.
Error codes
These errors return detail as an object with a code:
code | Status | Meaning |
|---|---|---|
card_required | 403 | Add a card before starting VMs or sessions. Includes billing_url. |
account_verification_required | 403 | Verify the account before starting VMs or sessions: sign in with Google or GitHub, or add a card. Includes sign_in_url and billing_url. |
vm_startup_reconciliation_required | 409 | A POST /v1/vms may have started a VM before it failed. Includes session_id, operation_id and "retry_safe": false. Do not create a replacement; list your VMs first. |
vm_memory_adjustment_refused | 409 | A POST /v1/vms got a VM but could not give it the memory you asked for. Includes session_id, operation_id and "retry_safe": false. |
New codes can be added. Treat a code you do not recognize according to its status.
{
"detail": {
"code": "card_required",
"message": "Add a card to start VMs or sessions. You will not be charged on this tier.",
"billing_url": "https://..."
}
}
Request ID
API responses carry an X-Request-ID header. Send your own X-Request-ID and the API returns the same value. Include it when you contact support about a failed request.
Responses produced by the proxy in front of the API (a 413, a share-link 429, a 502 while the API is unreachable) and an unhandled 500 do not carry it.
Status codes
| Status | What it means | What to do |
|---|---|---|
400 Bad Request | The request passed schema validation but was rejected by a check, for example an Idempotency-Key longer than 200 characters or a malformed ID. | Fix the request. Do not retry it unchanged. |
401 Unauthorized | No API key, or the key is unknown, revoked or expired. A bad key returns {"detail": "API Key: Invalid or inactive API key"}. | Check the X-API-Key header. Do not retry. |
402 Payment Required | Returned by POST /execute and POST /execute_async when the account cannot run code, for example when the Free plan's credits are used up or a paid subscription is not active. detail says which. | Fix billing in the dashboard. Do not retry until then. |
403 Forbidden | The account may not do this: the resource belongs to another account, the account is disabled, or a new account must be verified (detail is an object with a code, see above). GET /v1/users/me also answers 403 with "Invalid or inactive API key" for a bad key. | Read detail. Do not retry unchanged. |
404 Not Found | The resource does not exist or is not yours. An unknown path returns {"detail": "Not Found"}. An unknown share host returns {"detail": "Share not found"}. | Check the ID or path. |
405 Method Not Allowed | The path exists but not for this HTTP method. The Allow header lists the methods it takes. | Use a listed method. |
408 Request Timeout | POST /execute ran longer than the request's timeout: "Execution timed out after N seconds". | Raise timeout, or use POST /execute_async. The command may have had side effects, so do not blindly run it again. |
409 Conflict | The request conflicts with the current state: the VM is not active, an Idempotency-Key was reused or its first request is still running, a create needs reconciliation, or an SSH key is registered to another account. | Read detail. See Idempotent VM creation. |
413 Request Entity Too Large | The request body is over 64 MB. The proxy rejects it before it reaches the API, and the body is an HTML page, not JSON. | Send a smaller body. |
422 Unprocessable Entity | Validation failed. detail is a list. | Fix the fields named in loc. |
429 Too Many Requests | A rate limit or a plan limit was hit. | See Rate limits. |
500 Internal Server Error | Unexpected server error. The body may be JSON or the plain text Internal Server Error. | Retry reads. Before retrying a create, check whether it happened. |
502 Bad Gateway | A VM worker or the browser provider could not complete the request. The proxy also answers 502 with an HTML body while the API is unreachable. | Retry reads after a short wait. |
503 Service Unavailable | Temporarily unable to serve the request. Some 503 responses carry a Retry-After header with the number of seconds to wait. | Wait for Retry-After if present, otherwise back off, then retry. |
504 Gateway Timeout | A VM worker or provider did not answer in time. The change may still apply. | Check state before you retry a write. |
Retrying
Retry only when the status says the problem is temporary, and wait between attempts:
| Status | Retry? |
|---|---|
400, 401, 403, 404, 405, 413, 422 | No. The same request fails the same way. |
402 | Not until the billing problem is fixed. |
408 | Not blindly. The command may have run. |
409 | Only as detail says. Never when it contains "retry_safe": false. |
429 | Yes, after a wait. See Rate limits for the exception: a 429 for the concurrent VM limit does not clear until a VM stops. |
500, 502, 503, 504 | Reads, yes. Writes, only if repeating them is safe (below). |
Which requests are safe to repeat
| Request | Safe to repeat? |
|---|---|
GET | Yes. |
DELETE /v1/vms/{vm_id} | Yes. A repeat answers "status": "already_terminated", or 404 once the VM record is gone. |
Other DELETE requests | Yes. A repeat acts on the same ID and may answer 404. |
POST /v1/vms | Only with an Idempotency-Key header (below). Without one, each request can start another VM. |
POST /execute, POST /execute_async | No. A repeat runs the command again. |
Every other POST and PATCH | No idempotency mechanism. A repeat of a create, such as POST /v1/vms/{vm_id}/clone or POST /v1/snapshots, can create a second resource. Check the current state before repeating one that failed with a 5xx or timed out. |
Idempotent VM creation
POST /v1/vms accepts an Idempotency-Key header. Send the same key when you retry and the API starts at most one VM:
curl -X POST "https://api.instavm.io/v1/vms?wait=true" \
-H "X-API-Key: $INSTAVM_API_KEY" \
-H "Idempotency-Key: build-worker-7f3c2a" \
-H "Content-Type: application/json" \
-d '{"vm_lifetime_seconds": 600}'
How the key behaves:
-
The key is 1 to 200 characters. Anything else gets
400. -
Keys are scoped to your account.
-
The API remembers the path, query string and body sent with the key. Retry with exactly the same ones.
-
If the first request finished, a retry returns its response without starting another VM. The response is kept for 24 hours.
-
If the first request is still running, or failed after a VM may have been started, a retry gets
409withRetry-After: 15:{
"detail": {
"message": "VM creation is already in progress or awaiting reconciliation; do not create a replacement",
"session_id": "..."
}
} -
If the first request failed before the API asked a worker for a VM (for example with a
403or429), the key is released and a retry with it creates normally. -
The same key with a different path, query or body gets
409with"Idempotency-Key was already used for a different request".
Of the endpoints in the API reference, only POST /v1/vms reads Idempotency-Key. The Python and JavaScript SDKs do not send it.
SDK exceptions
| Status | Python SDK (0.26) | JavaScript SDK (0.17) |
|---|---|---|
401 | AuthenticationError | AuthenticationError |
402 | requests.exceptions.HTTPError (ExecutionError from execute()) | QuotaExceededError |
403 | ForbiddenError | ForbiddenError |
429 | RateLimitError | RateLimitError |
500, 502, 503, 504 | NetworkError | NetworkError |
Other 4xx | requests.exceptions.HTTPError from most methods (ExecutionError from execute()) | InstaVMError |
In Python, ForbiddenError and RateLimitError carry the parsed detail as e.args[0], which is a dict for the coded errors above. In JavaScript, an error raised for an HTTP response has statusCode and response (the parsed body), so read error.response.detail.
See Python error handling and Rate limits for the SDKs' retry behaviour.