Skip to main content
A failed connection or timed-out response does not prove that Telnyx failed to process the request. Retry decisions must account for the method, operation semantics, response status, and any product-specific idempotency mechanism.

​
Classify the operation

  • Read-only requests: GET operations 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 POST that can place a call, send a message, purchase a resource, or perform another side effect. First reconcile the resource or action state.
Consult the endpoint reference and product guide for supported idempotency fields such as 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, and 422: 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, and 504: 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:
Set the maximum attempts, delay per attempt, total elapsed time, and request timeout explicitly. Values depend on the product and operation latency contract. There is no universal Telnyx timeout or retry count.

​
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.