> Documentation index: https://docs.mayur.live/llms.txt

# Troubleshooting and Diagnostics

Diagnose common pipeline errors, configuration issues, and check service health.

Diagnose pipeline failures, configuration mistakes, and check system health across Voiceflow API components.

## Pipeline Error Codes

When an error occurs during an API request, the error response is formatted by `errorHandler`:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Recording not found"
  }
}
```

The following error structures and codes are returned across the API:

- `NOT_FOUND`: The requested route does not exist, or the target record cannot be found.
- `VALIDATION_ERROR`: The request parameters or body failed schema validation. The error message lists the affected fields.
- `PAYLOAD_TOO_LARGE`: The incoming HTTP request body exceeds Express payload size limits (HTTP status `413`).
- `BAD_REQUEST`: The request body could not be read or contains malformed JSON (HTTP status `400`).
- `INTERNAL_ERROR`: An unexpected server error occurred (HTTP status `500`).
- Custom application errors: Domain services raise `AppError` instances containing a defined HTTP status, error code, and descriptive message.

## Common Inngest and S3 Issues

Background processing runs asynchronously through Inngest at `/api/inngest`, while audio assets are uploaded directly from the browser to S3-compatible storage.

- **Audio direct-upload issues**: The browser uses a pre-signed URL returned during registration. The upload URL enforces exact audio content type and size limits. Ensure the client sends the exact content type and length specified during registration.
- **Background worker connection**: Inngest functions are served directly from the Express app at `/api/inngest`. Ensure the background job runner can communicate with this endpoint.
- **Server lifecycle on serverless platforms**: When running on Vercel (`VERCEL` environment variable set), Express does not bind to a standard port or manage shutdown signals through `src/server.ts`. Ensure environment variables and execution routes are properly mapped for serverless deployments.

## Authentication and Access Errors

Authentication is handled via Better Auth session management and role-based access middleware.

- **Unauthenticated requests**: If a valid session cookie or token is missing, the API rejects protected endpoints with an `AppError`.
- **Role restrictions**: Certain routes require specific roles:
  - Admin endpoints require an `admin` role and reject non-admin users.
  - Customer endpoints require customer access and reject unauthorized accounts.
- **Unverified accounts**: Users cannot log in until their email address has been verified.

## Health and Liveness Probes

Use the health endpoints to monitor container status and database connectivity.

### Liveness Probe

Checks if the Express process is running and responding to HTTP requests.

- **Endpoint**: `GET /health/live` (or root route handled by `getLiveness`)
- **Handler**: `getLiveness`
- **Success Response** (`200 OK`):
  ```json
  { "status": "ok" }
  ```

### Readiness Probe

Verifies if the API is ready to accept traffic by testing database connectivity via `isDatabaseUp`.

- **Endpoint**: `GET /health/ready` (handled by `getReadiness`)
- **Handler**: `getReadiness`
- **Database Check**: `isDatabaseUp` runs a query (`SELECT 1`) against the PostgreSQL database.
- **Success Response** (`200 OK`):
  ```json
  { "status": "ok" }
  ```
- **Failure Response** (`503 Service Unavailable`):
  ```json
  { "status": "database down" }
  ```