> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibely.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Format

> Standardized API error response format

Every Vibely API error response follows this structure:

```json theme={"system"}
{
  "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.) |

<Frame>
  <img src="https://cdn.vibely.sh/doc/v1/api-reference-errors.webp" alt="One error shape, stable codes" width="1200" height="675" />
</Frame>

## 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 |

The full set of error codes (\~70) is defined in `shared/src/types/errors.ts`.


## Related topics

- [API Overview](/api-reference/overview.md)
- [API authentication](/api-reference/auth.md)
- [Store API keys with secrets](/features/backend/secrets.md)
- [Set up workspace single sign-on (SSO)](/features/workspace/sso.md)
- [Prompt library](/prompting/library.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.