Errors

The API uses standard HTTP status codes and returns structured error responses with machine-readable error codes.

Error Response Format

All error responses follow a consistent JSON format with a code, message, and status field.

{
  "error": {
    "code": "invalid_request",
    "message": "sandboxId is required",
    "status": 400
  }
}

HTTP Status Codes

Code	Description
200	Success — request completed
201	Created — resource was created
204	No Content — resource was deleted
400	Bad Request — invalid parameters or missing required fields
401	Unauthorized — invalid or missing API key
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
409	Conflict — resource already exists or is in a conflicting state
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — unexpected server failure
503	Service Unavailable — sandbox runtime is temporarily unavailable

Error Codes

Code	Description
invalid_request	The request body is malformed or missing required fields
unauthorized	The API key is invalid, expired, or missing
forbidden	The API key does not have permission for this operation
not_found	The specified resource (sandbox, thread, etc.) does not exist
rate_limit_exceeded	Too many requests in a short period
sandbox_error	The sandbox encountered a runtime error
budget_exceeded	The request exceeded the maxBudgetUsd limit
stream_active	A stream is already active for this sandbox

Authentication Errors

All API endpoints require a valid API key passed via the Authorization: Bearer header. Missing or invalid keys return a 401 response.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

Rate Limiting

When rate limited, the response includes a retryAfter field indicating the number of seconds to wait before retrying.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 60 seconds.",
    "status": 429,
    "retryAfter": 60
  }
}