Third-Party API Integration — Work-in-Progress Brief

A developer has been building an integration between an internal notification service and a third-party SMS provider (Twilio). They've completed the core sending logic but have to hand over to a colleague before finishing the retry logic and error handling. Produce a document that lets the colleague continue.

What exists so far

The integration lives in src/notifications/sms/:

• client.py — wraps the Twilio REST client; send_sms() function works and has been tested against the Twilio sandbox
• models.py — SmsMessage dataclass defined; includes to, body, idempotency_key, and status fields
• tests/test_client.py — 8 unit tests using unittest.mock to stub the Twilio API; all passing

Still to build

• retry.py — exponential backoff on 429 (rate-limit) and 503 responses; not started
• dead_letter.py — messages that fail after max retries should be written to a dead-letter queue (SQS queue sms-dlq-prod); not started
• Webhook handler for delivery status callbacks — Twilio will POST to /webhooks/sms/status; route not registered yet

Decisions that haven't been finalised

• Maximum retry attempts: the architect mentioned 3 or 5 retries but didn't commit; this needs a decision before retry.py is written
• Whether the webhook handler should update SmsMessage.status synchronously or fire a background task

What the colleague should know

• Twilio credentials are in environment variables TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN — do NOT hardcode them or commit them to the repo
• The idempotency key must be passed as the X-Twilio-Idempotency-Token header; omitting it causes duplicate messages on retry — this burned an hour of debugging time

Write the handoff document.