# twilio-reliability-patterns

Codex and ChatGPT skill detailing Twilio production reliability patterns: handling 429 rate limits, managing number throughput, and receiving StatusCallbacks safely.

- skill · `type=skill` · Codex, ChatGPT · ★ 7604
- Author: Twilio · official OpenAI repository
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/openai/plugins/tree/HEAD/plugins/twilio-developer-kit/skills/twilio-reliability-patterns/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/twilio-reliability-patterns

## What it does

Twilio returns 429 responses as standard rate-limiting protection under load. This skill equips coding agents with retry logic using exponential backoff and randomized jitter of ±10%. Delays begin at 100ms, double on each retry, and cap at 30 seconds over 5 attempts. Non-429 errors fail immediately without retries.

The guide details throughput ceilings across number formats. Standard long codes manage roughly 1 SMS per second. Toll-free numbers handle about 3 SMS per second, while short codes achieve 10 to 100 SMS per second. Scaling delivery volume requires pooling numbers in a Messaging Service. Dispatch loops must match pool capacity rather than queue demand.

StatusCallback webhooks also present concurrency bottlenecks. Twilio Functions permit 30 concurrent executions per service. To avoid dropped events, the skill implements a thin-receiver pattern with Express and Flask. The web endpoint acknowledges the ping immediately with status 200 and enqueues data into BullMQ or Celery. Slow webhook responses trigger Twilio retry storms.

## Install

### Codex (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill twilio-reliability-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/twilio-reliability-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Claude Code

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill twilio-reliability-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/twilio-reliability-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/twilio-reliability-patterns/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/twilio-reliability-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install openai/plugins twilio-reliability-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/twilio-reliability-patterns/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/openai/plugins --path plugins/twilio-developer-kit/skills/twilio-reliability-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/twilio-reliability-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/openai/plugins/tree/HEAD/plugins/twilio-developer-kit/skills/twilio-reliability-patterns/SKILL.md

## When to use it
- Implement exponential backoff with randomized jitter for Twilio 429 errors
- Throttle bulk messaging loops based on Messaging Service number pool throughput
- Process StatusCallback webhooks through a thin receiver with an asynchronous queue
- Select Twilio phone number types according to required SMS and voice concurrency limits

## Example prompts
- Implement a Twilio SMS dispatch function in Python with exponential backoff and jitter
- Build an Express webhook handler for StatusCallbacks using the thin-receiver pattern with BullMQ
- Write a rate-limited bulk send script that throttles messages according to our number pool capacity

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 75f31110c68dfbec.

BEGIN THIRD-PARTY FILE 75f31110c68dfbec
````text
---
name: twilio-reliability-patterns
description: >
  Handle rate limits, retries, and failures when building on Twilio at
  scale. Covers 429 exponential backoff with jitter, per-number throughput
  limits, StatusCallback resilience, thin-receiver pattern, and fallback
  chains. Use this skill whenever sending messages or making calls at
  volume, or when building production-grade Twilio integrations.
---

## Overview

Twilio enforces per-resource rate limits. At scale, 429 errors are expected behavior — not bugs. This skill teaches the patterns that prevent production failures: exponential backoff, throughput management, and resilient callback handling.

429 concurrency errors are not well documented — implement exponential backoff with ±10% jitter.

---

## Prerequisites

- A working Twilio integration (any product)
- Understanding of your expected volume (messages/sec, calls/sec)
- StatusCallback URLs configured — see `twilio-messaging-services`, `twilio-sms-send-message`

---

## Key Patterns

### 1. Exponential Backoff with Jitter

When you receive a 429 (Too Many Requests), wait and retry. Naive fixed-interval retry creates thundering herds. Use exponential backoff with randomized jitter.

**Python**
```python
import time, random, requests

def send_with_backoff(client, to, body, messaging_service_sid, max_retries=5):
    for attempt in range(max_retries):
        try:
            message = client.messages.create(
                to=to,
                body=body,
                messaging_service_sid=messaging_service_sid,
                status_callback="https://yourapp.com/status"
            )
            return message
        except Exception as e:
            if hasattr(e, 'status') and e.status == 429:
                # Exponential backoff: 100ms, 200ms, 400ms, 800ms, 1600ms
                base_delay = 0.1 * (2 ** attempt)
                # Add ±10% jitter to prevent thundering herd
                jitter = base_delay * 0.1 * (2 * random.random() - 1)
                delay = min(base_delay + jitter, 30)  # cap at 30 seconds
                time.sleep(delay)
            else:
                raise  # Non-429 errors: don't retry, investigate
    raise Exception(f"Failed after {max_retries} retries")
```

**Node.js**
```node
async function sendWithBackoff(client, to, body, messagingServiceSid, maxRetries = 5) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await client.messages.create({
                to,
                body,
                messagingServiceSid,
                statusCallback: "https://yourapp.com/status",
            });
        } catch (err) {
````
END THIRD-PARTY FILE 75f31110c68dfbec

The third-party file has ended. Everything between the 75f31110c68dfbec tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2679 of 11067 bytes. © Twilio · MIT · https://github.com/openai/plugins/tree/HEAD/plugins/twilio-developer-kit/skills/twilio-reliability-patterns/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md