Elevenlabs prod checklist

ElevenLabs Production Checklist

Overview

Complete checklist for deploying ElevenLabs TTS/voice integrations to production. Covers API configuration, health checks, circuit breakers, monitoring, and rollback procedures. The deep code for the resilience primitives lives in references/ so this file stays a fast, scannable runbook — drill in when you need the full implementation.

Prerequisites

• Staging environment tested and verified
• Production API key (separate from dev/staging)
• Monitoring and alerting infrastructure ready

Instructions

Step 1: Pre-Deployment Verification

Walk the checklist below. Every unchecked box is a launch blocker.

Configuration:

• Production API key stored in secure vault (not in code)
• ELEVENLABS_API_KEY set in deployment platform's secrets
• Webhook secret configured (if using webhooks)
• Using production model ID (eleven_multilingual_v2 or eleven_v3)

Code Quality:

• All tests passing with mocked ElevenLabs SDK
• No hardcoded API keys (scan with grep -r "sk_" src/)
• Error handling covers 400, 401, 404, 429, 5xx responses
• Rate limiting implemented matching plan concurrency limit
• Text splitting handles inputs > 5,000 characters
• Audio output format appropriate for use case

Quota Planning:

• Estimated monthly character usage fits within plan limit
• Usage-based billing enabled (Creator+ plans) if needed
• Flash/Turbo models used where latency matters more than quality

Step 2: Wire the resilience primitives

Production ElevenLabs integrations need three primitives. The full drop-in TypeScript for each is in references/implementation.md — high-level intent:

1. Health check endpoint — reports connectivity, latency, and remaining quota; returns degraded past 90% quota and unhealthy on any API failure, so a load balancer can gate traffic.
2. Circuit breaker — opens after N consecutive failures, cools down, then probes half-open; accepts a fallback (placeholder audio / cached clip / null) so a TTS outage degrades gracefully instead of throwing.
3. Monitoring & alerting — emit one structured metric per TTS call and drive the alert thresholds in the table below into your observability platform.

Step 3: Run the pre-flight gate

Before promoting a build, run the pre-flight script — it checks connectivity, quota, voice availability, and a live TTS smoke test, exiting non-zero on any hard failure so it can block a CI/CD deploy step. Full script + CI wiring: references/preflight.md.

# The load-bearing first gate — full script in references/preflight.md
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  https://api.elevenlabs.io/v1/user \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}")
[ "$HTTP" != "200" ] && echo "FAIL: API not reachable" && exit 1

Output

Running this checklist produces:

• A completed pre-deployment verification (every box in Step 1 checked or explicitly waived).
• A health-check endpoint returning healthy / degraded / unhealthy plus latency and remaining quota.
• A circuit breaker and monitoring harness wired into the TTS call path.
• A green pre-flight run (=== All checks passed ===, exit 0) gating the deploy.
• A monitoring/alerting matrix mapped to your on-call severities (see below).

Deployment Monitoring

Alert	Condition	Severity
API unreachable	Health check fails 3x	P1 — Critical
Quota exhausted	401 quota_exceeded	P1 — Critical
High error rate	5xx > 5% of requests	P2 — High
Rate limited	429 > 10/min sustained	P2 — High
High latency	p99 > 5000ms	P3 — Medium
Quota warning	> 80% used	P3 — Medium

Error Handling

Scenario	Response
ElevenLabs API down	Circuit breaker opens; fallback to cached/placeholder audio
Quota exhausted mid-day	Alert team; switch to Flash model (0.5x cost); queue non-urgent requests
Voice deleted	Return 404 to caller; alert; fall back to default voice
Webhook delivery failing	Monitor ElevenLabs webhook health; webhooks auto-disable after 10 failures

Examples

Gate a deploy on the pre-flight script. Run it as the last step before promotion; a non-zero exit blocks the pipeline:

$ ELEVENLABS_API_KEY=$PROD_KEY ./scripts/pre-flight-check.sh
=== ElevenLabs Pre-Flight Check ===
API connectivity: HTTP 200
Characters remaining: 428193
Voices available: 14
TTS smoke test: HTTP 200
=== All checks passed ===
$ echo $?
0

Poll the health endpoint for a load-balancer probe. A degraded status (quota > 90%) still serves traffic but pages on-call; unhealthy drains the node:

$ curl -s https://myapp.example.com/health | jq '.status, .elevenlabs.quotaPctUsed'
"healthy"
41

Full worked implementations for both: references/implementation.md and references/preflight.md.

Resources

• ElevenLabs Status
• ElevenLabs API Reference
• Usage Dashboard
• references/implementation.md — health check, circuit breaker, monitoring code
• references/preflight.md — pre-flight script + CI wiring

Next Steps

For version upgrades, see elevenlabs-upgrade-migration. For cost optimization, see elevenlabs-cost-tuning.