API Reliability & Retries

When building applications with Telnyx APIs, you may encounter various reliability challenges that require robust error handling and retry strategies. These patterns apply across all Telnyx services including Voice, Messaging, Cloud Storage, and more.

Applications may encounter the following situations across any Telnyx API:

• 5XX Errors: Server errors (500, 501, 503, 504) that indicate temporary service issues
• Network Timeouts: Requests that don't complete within expected timeframes
• Duplicate Responses: Identical responses that may occasionally be delivered

Telnyx carefully monitors all API platforms for 5XX errors, latency, and duplicate responses, and actively works to keep all of these to a minimum across all services.

For added reliability, there are several steps developers can take to handle errors, latency, and duplicate responses across any Telnyx API:

• Send a unique identifier (such as command_id, idempotency_key, or similar) as part of your API requests
• The identifier must be unique for each operation. We suggest using UUIDv4
• This prevents duplicate operations when retries are necessary

• Retry on 5XX Errors: If your application receives a 500-level error, implement exponential backoff and retry
• Timeout Handling: If your application fails to receive an HTTP response within a reasonable timeframe (typically 500ms-5s depending on the operation), retry the request
• Maximum Retry Attempts: Implement a maximum retry limit (typically 3-5 attempts) to avoid infinite loops

• Exponential Backoff: Increase wait time between retries (e.g., 1s, 2s, 4s, 8s)
• Circuit Breaker: Temporarily stop making requests if error rates exceed thresholds
• Graceful Degradation: Design your application to continue functioning even when some API calls fail