Error Reference

Common API error responses and how to fix them.

HTTP Status Codes

The VSee API uses standard HTTP status codes. Here are the most common ones you'll encounter:

Status	Meaning	What to Do
200	Request succeeded.	N/A — success!
400	Missing required fields or invalid parameters.	Check your request body and query parameters. Ensure all required fields are included.
401	Authentication failed.	Check your token is valid, not expired, and for the correct environment.
403	You don't have permission for this action.	You may be using the wrong token type. Admin endpoints require the Clinic Admin API Token.
404	The resource or endpoint doesn't exist.	Verify the URL path and any ID parameters. Check that you're using the correct base URL.
422	Validation failed on the request data.	Check field formats, required fields, and data types match the spec.
429	Too many requests.	Slow down your request rate. Implement exponential backoff.
500	Something went wrong on the server.	Retry after a brief delay. If persistent, contact VSee support.

Common Error Scenarios

403403 Bad Request — Wrong Token Type

{
  "code": "85FBEFE5",
  "message": "Bad Request"
}

Cause: You're using a user session token (from login/SSO) on an endpoint that requires the Clinic Admin API Token.

Fix: Use the Clinic Admin API Token from your admin dashboard (Developers → App → Edit App) instead of a user session token. This is the most common error when integrating the Rooms API, Webhooks, or Recordings API.

401401 Unauthorized — Invalid or Expired Token

{
  "message": "Unauthorized Access"
}

Cause: Your token is invalid, expired, or from the wrong environment (e.g., staging token used against production).

Fix: Re-authenticate to get a fresh token. Verify you're using the correct base URL for your environment (api.vseepreview.com for staging, api.vsee.me for production).

400400 Bad Request — Missing Required Field

{
  "message": "Bad Request",
  "errors": {
    "title": "The title field is required"
  }
}

Cause: A required parameter or body field is missing from your request.

Fix: Check the endpoint's parameter documentation. Ensure all required fields are present in your request body and headers.

0CORS Error (Browser)

Access to fetch at 'https://api.vsee.me/...' has been blocked by CORS policy

Cause: You're calling the API directly from browser-side JavaScript.

Fix: The VSee API does not support CORS. Route all API calls through your backend server. See the Getting Started guide for the recommended architecture.

403403 Forbidden — Environment Mismatch

{
  "message": "Bad Request"
}

Cause: You're using staging credentials against production (or vice versa), or the account code doesn't match the base URL.

Fix: Ensure all of these match the same environment: base URL, Account Code, API Token, API Key/Secret. Staging uses *.vseepreview.com; production uses *.vsee.me.

Debugging Tips

Check the HTTP status code first. It tells you the category of error (auth, validation, server, etc.).

Read the error message and code. The response body often contains a machine-readable code and human-readable message.

Test with cURL first. Use the generated cURL command from the API docs to rule out issues with your HTTP library or framework.

Verify the auth badge. Check the authentication badge on the endpoint you're calling. Make sure you're using the right token type.

Test in staging first. Always build and test against api.vseepreview.com before moving to production.

Error Response Format

Most error responses follow this format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}

Some validation errors include an errors object with field-level details:

{
  "message": "Bad Request",
  "errors": {
    "field_name": "Description of what's wrong with this field"
  }
}