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

# Errors

The Faseeh API uses standard HTTP status codes and custom error codes to indicate the type of error that occurred. All errors are returned in a consistent JSON format.

## Error Response Format

All error responses follow this structure:

```json theme={null}
{
  "errorCode": 40001,
  "errorMessage": "Error description"
}
```

The HTTP status code in the response header corresponds to the error type, while `errorCode` provides a specific numeric code for programmatic error handling.

## Error Types

### AuthenticationError

Occurs when authentication fails or API key is invalid.

**Status Code**: `401` (Unauthorized)

**Error Codes**: `40101`

**Common Scenarios**:

* Missing `x-api-key` header
* Invalid API key format
* Expired API key
* Revoked or deleted API key
* Invalid JWT signature

**Properties**:

* `errorCode` (number): Error code `40101`
* `errorMessage` (string): Human-readable error message

**Example**:

```json theme={null}
{
  "errorCode": 40101,
  "errorMessage": "Invalid API key"
}
```

***

### ValidationError

Occurs when request validation fails due to invalid or missing parameters.

**Status Code**: `400` (Bad Request)

**Error Code**: `40001`

**Common Scenarios**:

* Empty or missing required fields
* Text too short (less than 3 words or 10 characters)
* Invalid parameter values (out of range)
* Invalid message types (WebSocket)
* Missing voice embeddings
* Payload too large

**Properties**:

* `errorCode` (number): Error code `40001`
* `errorMessage` (string): Human-readable error message describing the validation issue

**Example**:

```json theme={null}
{
  "errorCode": 40001,
  "errorMessage": "Text must have at least 3 words and 10 characters"
}
```

***

### InsufficientBalanceError

Occurs when the user's account balance is insufficient to complete the request.

**Status Code**: `402` (Payment Required)

**Error Code**: `40201`

**Properties**:

* `errorCode` (number): Error code `40201`
* `errorMessage` (string): Error message describing the insufficient balance with required and available amounts

**Example**:

```json theme={null}
{
  "errorCode": 40201,
  "errorMessage": "Insufficient wallet balance. Required: $0.50, Available: $0.25"
}
```

**Note**: The error message includes the exact amount required and the current available balance. Users should recharge their account to continue using the API.

***

### ModelAccessError

Occurs when the user attempts to access a model they don't have permission to use.

**Status Code**: `403` (Forbidden)

**Error Code**: `40301`

**Properties**:

* `errorCode` (number): Error code `40301`
* `errorMessage` (string): Error message describing the access restriction

**Example**:

```json theme={null}
{
  "errorCode": 40301,
  "errorMessage": "This model is not enabled for your account. Please contact support@faseeh.ai to get access."
}
```

**Note**: Some models require special access. Contact support to request access to restricted models.

***

### ConcurrencyLimitError

Occurs when the user has exceeded their concurrent request limit based on their subscription plan.

**Status Code**: `429` (Too Many Requests)

**Error Code**: `42901`

**Properties**:

* `errorCode` (number): Error code `42901`
* `errorMessage` (string): Error message describing the concurrency limit with current and maximum values

**Example**:

```json theme={null}
{
  "errorCode": 42901,
  "errorMessage": "Concurrency limit exceeded. Maximum 5 concurrent requests allowed. Current: 6. Please upgrade your plan https://app.faseeh.ai/en/subscription or contact support@faseeh.ai for more information."
}
```

**Concurrency Limits by Plan**:

* **Basic Plan**: 2 concurrent requests
* **Starter Plan**: 5 concurrent requests
* **Growth Plan**: 10 concurrent requests
* **Scale Plan**: 20 concurrent requests
* **Free/No Plan**: 1 concurrent request

**Note**: Wait for current requests to complete, or upgrade your plan to increase your concurrency limit.

***

### InternalError

Occurs when an internal server error happens or external services fail.

**Status Code**: `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout)

**Error Code**: `50001`

**Common Scenarios**:

* Internal server errors
* External API failures (ElevenLabs)
* Database connection issues
* File storage failures (R2)
* Request timeouts
* Connection errors

**Properties**:

* `errorCode` (number): Error code `50001`
* `errorMessage` (string): Error message describing the issue

**Example**:

```json theme={null}
{
  "errorCode": 50001,
  "errorMessage": "Internal server error"
}
```

***

### NotFoundError

Occurs when a requested resource doesn't exist.

**Status Code**: `404` (Not Found)

**Error Code**: `40401` (or `50001` for some cases)

**Common Scenarios**:

* Model not found
* Voice not found
* Resource endpoint not found

**Properties**:

* `errorCode` (number): Error code (typically `40401` or `50001`)
* `errorMessage` (string): Error message describing what wasn't found

**Example**:

```json theme={null}
{
  "errorCode": 40401,
  "errorMessage": "Model not found: faseeh-v2-preview"
}
```

***

## Error Code Reference

| Error Code | HTTP Status     | Error Type               | Description                               |
| ---------- | --------------- | ------------------------ | ----------------------------------------- |
| `40001`    | 400             | ValidationError          | Request validation failed                 |
| `40101`    | 401             | AuthenticationError      | Authentication failed or invalid API key  |
| `40201`    | 402             | InsufficientBalanceError | Insufficient account balance              |
| `40301`    | 403             | ModelAccessError         | Model access denied                       |
| `40401`    | 404             | NotFoundError            | Resource not found                        |
| `42901`    | 429             | ConcurrencyLimitError    | Concurrent request limit exceeded         |
| `50001`    | 500/502/503/504 | InternalError            | Internal server or external service error |

***

## Handling Errors

When an error occurs, check the HTTP status code in the response header and the `errorCode` field in the response body to determine the appropriate action:

### 400 - ValidationError

* **Action**: Review the request parameters and fix validation issues
* **Common fixes**:
  * Ensure all required fields are provided
  * Check text length meets minimum requirements (3 words, 10 characters)
  * Verify parameter values are within valid ranges
  * Reduce payload size if exceeding limits

### 401 - AuthenticationError

* **Action**: Verify your API key is correct and valid
* **Common fixes**:
  * Ensure `x-api-key` header is included in the request
  * Check that the API key hasn't expired
  * Verify the API key format is correct
  * Generate a new API key if the current one was revoked

### 402 - InsufficientBalanceError

* **Action**: Recharge your account balance
* **Common fixes**:
  * Check your current balance
  * Add funds to your account via the dashboard
  * Enable auto-topup to automatically recharge when balance is low
  * Verify the cost of the operation before making the request

### 403 - ModelAccessError

* **Action**: Request access to the model
* **Common fixes**:
  * Contact [support@faseeh.ai](mailto:support@faseeh.ai) to request access
  * Verify your subscription plan includes access to the model
  * Check if the model ID is correct

### 404 - NotFoundError

* **Action**: Verify the resource exists
* **Common fixes**:
  * Check that the model ID, voice ID, or resource ID is correct
  * Verify the resource hasn't been deleted
  * Ensure you're using the correct endpoint

### 429 - ConcurrencyLimitError

* **Action**: Reduce concurrent requests or upgrade your plan
* **Common fixes**:
  * Wait for current requests to complete
  * Reduce the number of simultaneous API calls
  * Upgrade your subscription plan to increase concurrency limits
  * Implement request queuing in your application

### 500/502/503/504 - InternalError

* **Action**: Retry the request or contact support
* **Common fixes**:
  * Retry the request after a short delay (exponential backoff recommended)
  * Check the error message for specific details
  * If the issue persists, contact [support@faseeh.ai](mailto:support@faseeh.ai) with:
    * The error code and message
    * The request that caused the error
    * Timestamp of the error
  * For external API errors, wait a few minutes and retry

***

## Best Practices

1. **Implement Retry Logic**: For 500-level errors, implement exponential backoff retry logic
2. **Handle Rate Limits**: Monitor for 429 errors and implement request queuing
3. **Validate Inputs**: Prevent 400 errors by validating inputs before sending requests
4. **Monitor Balance**: Check balance before making requests to avoid 402 errors
5. **Cache API Keys**: Store API keys securely and handle expiration gracefully
6. **Error Logging**: Log all errors with context for debugging
7. **User-Friendly Messages**: Display user-friendly error messages based on error codes

***

## WebSocket Errors

For WebSocket connections, errors are sent as JSON messages:

```json theme={null}
{
  "type": "error",
  "message": "Error description"
}
```

Common WebSocket errors:

* Missing authentication: `"x-api-key or Authorization header is required. Provide it in query string, headers, or initConnection message."`
* Invalid message type: `'Invalid message type. Expected "voice-request"'`

***

## Support

If you encounter errors that aren't covered in this documentation or need assistance:

* **Email**: [support@faseeh.ai](mailto:support@faseeh.ai)
* **Documentation**: [https://docs.faseeh.ai](https://docs.faseeh.ai)
* **Status Page**: Check our status page for service updates