API Usage

• Use async mode for audio files longer than 5 minutes
• Implement proper error handling and retry logic (see examples below)
• Respect rate limits and implement exponential backoff
• Cache results when appropriate to reduce API calls
• Use webhooks instead of polling for async job notifications

Error Handling

Always check the HTTP status code and handle errors gracefully. Here is a reusable pattern for making API calls with proper error handling and retry logic:

import requests
import time


def lesan_request(method, endpoint, max_retries=3, **kwargs):
    """Make an API request with error handling and retry logic."""
    url = f"https://asr.lesan.ai{endpoint}"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        **kwargs.pop("headers", {})
    }


    for attempt in range(max_retries):
        try:
            response = method(url, headers=headers, **kwargs)


            if response.ok:
                return response.json()


            error = response.json().get("error", {})


            # Retry on rate limits and server errors
            if response.status_code == 429:
                wait = error.get("retry_after", 2 ** attempt)
                print(f"Rate limited. Retrying in {wait}s...")
                time.sleep(wait)
                continue
            elif response.status_code >= 500:
                wait = 2 ** attempt
                print(f"Server error. Retrying in {wait}s...")
                time.sleep(wait)
                continue


            # Don't retry client errors
            raise Exception(f"{error.get('code')}: {error.get('message')}")


        except requests.ConnectionError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise


    raise Exception("Max retries exceeded")


# Usage
result = lesan_request(
    requests.post, "/transcribe",
    json={"audio_url": "https://example.com/audio.mp3", "language": "am", "mode": "sync"}
)
print(result["text"])

See the Error Codes reference for all error types and handling strategies.

Audio Quality

• Use high-quality audio files for better transcription accuracy
• Record at 16kHz or higher sample rate — see Audio Formats
• Use FLAC or WAV for best quality, MP3 for smaller file sizes
• Minimize background noise when possible
• For best results, use audio with clear speech and minimal overlapping speakers

Security

• Never expose API keys in client-side code — use publishable keys for browser apps
• Store keys securely using environment variables
• Rotate API keys regularly — especially when team members change
• Use restricted keys with minimal scopes for each service
• Enable IP whitelisting for server-side keys
• Monitor API key usage for suspicious activity

Performance

• Use batch processing for multiple files instead of individual requests
• Use webhooks for async job notifications instead of polling
• If polling, use 5-second intervals with exponential backoff
• Optimize audio file sizes before uploading — downsample to 16kHz mono
• Use WebSocket streaming for real-time use cases instead of repeated sync calls

Production Checklist

Before deploying to production, verify the following:

• Error handling — All API calls have try/catch with retry logic for 429 and 500 errors
• API keys — Using live keys (not test/dev), stored in environment variables
• Rate limits — Monitoring usage via X-RateLimit-Remaining headers
• Webhooks — Signature verification is implemented and tested
• Timeouts — HTTP client timeouts are set (30s for sync, 10s for status checks)
• Logging — Logging request IDs and error codes for debugging
• Audio format — Files are in a supported format and under 500 MB
• Scopes — API keys have only the minimum required scopes

For more information, check out our other guides and the API Reference.