UltraVoiceDocs

Errors & Rate Limits

All API errors follow a consistent JSON format with an HTTP status code and a machine-readable error code.

Error Response Format

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "JWT token is expired",
    "details": {}
  }
}

HTTP Status Codes

  • 200 OK — Request succeeded
  • 201 Created — Resource successfully created
  • 400 Bad Request — Invalid request body or missing required fields
  • 401 Unauthorized — Missing or invalid JWT token
  • 403 Forbidden — Valid token but insufficient permissions
  • 404 Not Found — Resource does not exist
  • 409 Conflict — Resource already exists (e.g., duplicate email)
  • 422 Unprocessable Entity — Validation failed (field-level errors)
  • 429 Too Many Requests — Rate limit exceeded
  • 500 Internal Server Error — Unexpected server error
  • 503 Service Unavailable — Upstream provider (LLM/ASR/TTS) is down

Authentication Errors

  • MISSING_TOKEN — No Authorization header provided
  • INVALID_TOKEN — Token signature is invalid
  • EXPIRED_TOKEN — Token has expired (24h access, 7d refresh)
  • INVALID_OTP — OTP code is incorrect
  • OTP_EXPIRED — OTP expired (10 minute window)
  • OTP_MAX_ATTEMPTS — Maximum 5 OTP attempts exceeded
  • EMAIL_NOT_VERIFIED — Account not verified via OTP

Provider Errors

  • PROVIDER_API_KEY_INVALID — The configured provider API key is rejected
  • PROVIDER_QUOTA_EXCEEDED — Provider rate limit or quota reached
  • PROVIDER_TIMEOUT — Provider did not respond within timeout
  • PROVIDER_NOT_CONFIGURED — Agent is missing LLM, ASR, or TTS provider

Rate Limits

  • Authentication endpoints — 10 requests/minute per IP
  • REST API endpoints — 100 requests/minute per user
  • Session start — 20 sessions/minute per user
  • Concurrent WebSocket sessions — 50 per user
  • Tool executions — 200 per minute per agent
⚠️

Exceeding rate limits returns HTTP 429. Implement exponential backoff with jitter in your retry logic.

System Limits

  • Maximum session duration — 60 minutes
  • Maximum conversation turns — 500 per session
  • Maximum knowledge base entries — 500 per workspace
  • Maximum tools per agent — 20
  • Maximum audio frame size — 65536 bytes
  • Maximum dynamic_variables per session — 50 key-value pairs