Idempotency

Every SMS API request requires an Idempotency-Key.

Idempotency prevents the same request from being processed multiple times when your application retries a request.

Header

Send a unique value in the Idempotency-Key header:

Idempotency-Key: unique-request-key

For example:

Idempotency-Key: 7f8e2d91-5c34-4a21-b876-19d5e4f20381

The key should be unique for each new SMS request.

Example request

POST {{BASE_URL}}/api/v1/sms
X-API-KEY: your-api-key
X-API-SECRET: your-api-secret
Idempotency-Key: 7f8e2d91-5c34-4a21-b876-19d5e4f20381
Content-Type: application/json

{
  "msisdns": [
    "254701234567"
  ],
  "message": "Hello",
  "sender_name": "VOLCHA"
}

Request lifecycle

An idempotency key is associated with the request while it is being processed.

There are three possible situations when the same key is used again.

Different request

If the same idempotency key is used with different request data, the request is rejected.

{
  "success": false,
  "message": "The idempotency key has already been used for a different request.",
  "error": "INVALID_REQUEST",
  "data": null
}

Request already completed

If the request associated with the key has already completed, another request using the same key is rejected.

{
  "success": false,
  "message": "The request has already been completed.",
  "error": "INVALID_REQUEST",
  "data": null
}

Request is still processing

If the original request is still being processed, another request using the same key is rejected.

{
  "success": false,
  "message": "A request with this idempotency key is already being processed.",
  "error": "INVALID_REQUEST",
  "data": null
}

Key expiration

Idempotency keys are retained for 60 seconds.

After the retention period expires, the key can be used again.

Recommended usage

Generate a new idempotency key for every new SMS request.

If your application retries a request because of a network timeout or another temporary failure, reuse the same idempotency key rather than generating a new one.

This allows the API to identify the retry as the same request.

New request

Request A → Key: abc-123

Retry

Request A retry → Key: abc-123

Do not do this:

Request A → Key: abc-123
Request A retry → Key: xyz-789

Using a new key for a retry can cause the request to be treated as a new SMS request.