Classify the operation
- Read-only requests:
GEToperations are normally safe to retry when no response was received or a retryable status was returned. - Idempotent mutations: Retry only when the endpoint contract or an idempotency mechanism makes repeated execution safe.
- Non-idempotent actions: Do not automatically retry a timed-out
POSTthat can place a call, send a message, purchase a resource, or perform another side effect. First reconcile the resource or action state.
command_id or an idempotency key. Do not invent or send an idempotency header that the endpoint does not declare.
Decide by failure class
400,401,403,404, and422: Correct the request, credential, access, or resource state. Do not retry unchanged input.409: Reconcile current state and follow endpoint-specific conflict guidance.429: Delay according to the rate-limit response and retry within a bounded policy.500,502,503, and504: Retry only when the operation is safe to repeat.- Connection reset or timeout before a response: Treat the outcome as unknown for mutating operations.
Apply bounded exponential backoff
Use exponential backoff with jitter:Preserve observability
Record the endpoint and method, HTTP status and Telnyx error code, request or correlation identifier, product resource identifier, attempt number, delay, and supported idempotency identifier. Do not log credentials or sensitive payloads.Use SDK defaults deliberately
Server-side SDKs expose retry and timeout controls. Review the language-specific SDK guides before overriding defaults. Application retries and SDK retries can multiply each other; keep one bounded retry budget for the complete operation.Related
- Rate limiting
- Requests and responses
- API troubleshooting
- Voice API command retries:
command_idand retry advice for Call Control commands, including media streaming