{
"error": "Human-readable message",
"code": "MACHINE_READABLE_CODE",
"status": 400,
"request_id": "req_abc123",
"error_ref": "3F9A2C11",
"details": {}
}
| Field | Type | Description |
|---|---|---|
error | string | User-safe description of what went wrong |
code | string | Stable machine-readable code (see table below) |
status | number | HTTP status code |
request_id | string | Per-request correlation id — quote this in support |
error_ref | string | Opaque per-occurrence id (stream errors only) — joins one report to one server log line |
details | object | Optional structured payload (upgrade URLs, retry timing, etc.) |
Error codes
Authentication (4xx)
| Code | Meaning |
|---|---|
AUTH_REQUIRED | No Bearer token provided |
TOKEN_INVALID | Token is malformed or expired |
TOKEN_EXPIRED | Token has passed its expiry |
ACCESS_DENIED | Valid token but insufficient permissions |
Projects (4xx)
| Code | Meaning |
|---|---|
PROJECT_NOT_FOUND | Project does not exist or caller has no access |
NOT_MOBILE | Operation requires a mobile-mode project |
BUILD_IN_PROGRESS | A build is already running for this project |
BUILD_NOT_FOUND | Referenced build does not exist |
BUILD_NOT_FINISHED | Build exists but hasn’t completed |
Entitlement (4xx)
| Code | Meaning |
|---|---|
OUT_OF_CREDITS | Account has no remaining credits |
ENTITLEMENT_REQUIRED | Current plan does not include this feature |
ENTITLEMENT_EXCEEDED | Plan limit reached (members, builds, etc.) |
MEMBER_CAP_EXCEEDED | Workspace member limit hit |
Sandbox / Build (5xx)
| Code | Meaning |
|---|---|
SANDBOX_CREATE_FAILED | Could not provision a sandbox |
SANDBOX_SETUP_FAILED | Sandbox started but setup script failed |
SANDBOX_UNAVAILABLE | Sandbox provider is unreachable |
PROJECT_INIT_FAILED | Project scaffolding failed in sandbox |
RELAY_STALLED | Sandbox dev server stopped responding |
Provider (5xx)
| Code | Meaning |
|---|---|
PROVIDER_UNAVAILABLE | LLM provider is unreachable |
MODEL_UNAVAILABLE | Specific model is overloaded or down |
SERVICE_BUSY | Server is at capacity — retry with backoff |
RATE_LIMITED | Too many requests from this caller |
Internal (5xx)
| Code | Meaning |
|---|---|
INTERNAL_ERROR | Unanticipated server fault |
DATABASE_UNAVAILABLE | Supabase/Postgres is unreachable |
Validation (4xx)
| Code | Meaning |
|---|---|
VALIDATION_ERROR | Request body failed schema validation |
INVALID_SUBSCRIPTION | Push subscription payload is malformed |
shared/src/types/errors.ts.