Retries and idempotency

What gets retried

The client retries requests that are safe to repeat, so a passing blip on the network or a busy moment on the server does not turn into a failure in your code.

• GET requests are always retried, since reading is safe to repeat.
• A 429 Too Many Requests response is always retried.
• Network errors and 5xx responses on a send are retried only when you supply an idempotency key, so a message is never sent twice by accident.

Retries use exponential backoff with a little random jitter. When the API returns a Retry-After header, the client waits exactly that long instead.

Tune it

Set the ceiling on retry attempts and the request timeout when you build the client:

from onesms import Client

client = Client("1sk_your_api_key", max_retries=5, timeout=15.0)

Set max_retries=0 to turn retries off.

Idempotency keys

An idempotency key is a string you attach to a send. The API remembers it for 24 hours and refuses to send the same request twice, which is what makes a send safe to retry.

client.send_otp(
    "994501234567",
    "Your code is 123456",
    idempotency_key="order-4821-otp",
)

Choose a key that is stable for the action you are performing, such as an order id combined with the message type. If the first attempt reached the API but the response got lost on the way back, sending again with the same key returns the original result rather than a second message.

Supplying a key also turns on retries for network and server errors on that send, as described above.

Note

An idempotency key is at most 128 characters. A longer key raises OneSmsValidationError before anything is sent.