Help

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:

{
  "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): 
    { "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): 
    { "status": "ok" }
  • Failure Response (503 Service Unavailable): 
    { "status": "database down" }