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:
Code Quality:
Quota Planning:
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:
- 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.
- 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.
- 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.
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
Next Steps
For version upgrades, see elevenlabs-upgrade-migration. For cost optimization, see elevenlabs-cost-tuning.
