Skip to main content
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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "errorCode": 40401,
  "errorMessage": "Model not found: faseeh-v2-preview"
}

​
Error Code Reference

Error CodeHTTP StatusError TypeDescription
40001400ValidationErrorRequest validation failed
40101401AuthenticationErrorAuthentication failed or invalid API key
40201402InsufficientBalanceErrorInsufficient account balance
40301403ModelAccessErrorModel access denied
40401404NotFoundErrorResource not found
42901429ConcurrencyLimitErrorConcurrent request limit exceeded
50001500/502/503/504InternalErrorInternal 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 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 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: 
{
  "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: