Go SDK errors, retries, and timeouts - Telnyx

Errors

When the API returns a non-success status code, we return an error with type *telnyx.Error. This contains the StatusCode, *http.Request, and *http.Response values of the request, as well as the JSON of the error body (much like other response objects in the SDK). To handle errors, we recommend that you use the errors.As pattern:

_, err := client.NumberOrders.New(context.TODO(), telnyx.NumberOrderNewParams{
	PhoneNumbers: []telnyx.NumberOrderNewParamsPhoneNumber{{
		PhoneNumber: "+15558675309",
	}},
})
if err != nil {
	var apierr *telnyx.Error
	if errors.As(err, &apierr) {
		println(string(apierr.DumpRequest(true)))  // Prints the serialized HTTP request
		println(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response
	}
	panic(err.Error()) // GET "/number_orders": 400 Bad Request { ... }
}

When other errors occur, they are returned unwrapped; for example, if HTTP transport fails, you might receive *url.Error wrapping *net.OpError.

Timeouts

Requests do not time out by default; use context to configure a timeout for a request lifecycle. Note that if a request is retried, the context timeout does not start over. To set a per-retry timeout, use option.WithRequestTimeout().

// This sets the timeout for the request, including all the retries.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
client.NumberOrders.New(
	ctx,
	telnyx.NumberOrderNewParams{
		PhoneNumbers: []telnyx.NumberOrderNewParamsPhoneNumber{{
			PhoneNumber: "+15558675309",
		}},
	},
	// This sets the per-retry timeout
	option.WithRequestTimeout(20*time.Second),
)

Retries

Certain errors will be automatically retried 2 times by default, with a short exponential backoff. We retry by default all connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors. You can use the WithMaxRetries option to configure or disable this:

// Configure the default for all requests:
client := telnyx.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Override per-request:
client.NumberOrders.New(
	context.TODO(),
	telnyx.NumberOrderNewParams{
		PhoneNumbers: []telnyx.NumberOrderNewParamsPhoneNumber{{
			PhoneNumber: "+15558675309",
		}},
	},
	option.WithMaxRetries(5),
)

⌘I