# Error Reference
URL: https://developers.vsee.io/guides/error-reference

### 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
1Check the HTTP status code first. It tells you the category of error (auth, validation, server, etc.).

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

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

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

5Test 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"
  }
}