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 |
| 422 | Unprocessable Entity - request is well-formed but violates a semantic constraint (e.g. vault cap, missing coverage) |
| 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 |
| validation_error | A field fails validation (e.g. vault name too long, metadata caps exceeded) |
| 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, vault, credential) does not exist |
| conflict | Duplicate credential for the same serverUrl in a vault, or hard-delete attempted without prior archive |
| credential_cap_exceeded | Attempted to create a 21st active credential in a vault (max 20 per vault) |
| vault_coverage_missing | The session's resolved vaults do not cover all MCP servers declared on the agent (when VAULT_COVERAGE_MODE is strict) |
| rate_limit_exceeded | Too many requests in a short period |
| sandbox_error | The sandbox encountered a runtime error |
| budget_exceeded | The request exceeded a configured budget 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
}
}