Checklist

Everything here is a failure someone has actually shipped. Each item links to the page that explains it.

Credentials

• The API key's scopes match what you call — ingest to submit, webhooks:manage to register endpoints. A missing scope is a 403 that never resolves on retry. → Authentication
• Keys are held in a secret store, not in source or an environment file in your repository.
• You know how to rotate a key without downtime, and have done it once.

Webhooks

• The signing secret is stored. Registration returns it once and no route will ever show it to you again. (Rotating mints a new secret, shown once in the same way — it is not a second read of the old one.) → Quickstart
• The signature is verified before the body is parsed. Not after, not conditionally. → Verifying signatures
• The timestamp is checked against a replay window, and old deliveries are rejected.
• Your endpoint returns 2xx quickly and does the real work asynchronously. Anything else counts as a failed delivery. → Retries
• Duplicate deliveries are safe. Retries mean the same event can arrive more than once.
• You know how to rotate the signing secret without dropping deliveries, and have done it once. There is no overlap window — the old secret stops working the instant you rotate, and a botched rotation fails silently, with every delivery rejected by your own verification and no error response to alert you. → Rotating secrets
• The endpoint is reachable from the public internet and its TLS certificate is valid. Confirmed with a real test delivery, not assumed. → Webhooks overview

Submitting calls

• provider_call_id and idempotency_key are sent on every call. They are the only way to join a webhook back to a record in your system. → Correlation
• A 200 from POST /calls is handled as success, not as an error. It means the call was already ingested. → Idempotency
• upload.headers from the presign response are applied to your PUT verbatim. → Uploading audio

Failure handling

• 429 is checked for an error key before any retry is scheduled — an allowance refusal wears the same status as a throttle. → Errors
• Retry-After is honoured on genuine throttles. → Rate limits
• The stop-and-tell-a-human codes page a person instead of retrying: ai_budget_exhausted, ingest_subscription_lapsed, insufficient_scope.
• The daily and monthly allowance codes are handled differently. Midnight clears one and does nothing for the other.
• Failed submissions are queued and replayable — not dropped, and not retried in a tight loop.

Before you switch traffic on

• One real call has gone the whole way through: presign, upload, submit, verified webhook.
• You have alerting on webhook deliveries that stop arriving, which is the failure mode with no error response attached to it.