Skip to main content

API Idempotency

The Balanceless Card Model API suite supports idempotent operations to help prevent duplicate processing in case of retries.

Idempotency Key​

All applicable API requests must include the following header:

x-request-id: <unique-client-generated-id>
  • This ID must be unique per operation.
  • If a request with the same x-request-id is received more than once, the API will return the result of the original request, without reprocessing it.
  • This applies to both 2xx (success) and 4xx (client error) responses; no side effects will occur on repeated requests with the same ID.

Handling Server Errors (5xx)​

If a request results in a 5xx error, the response will include a flag to indicate whether the operation is retryable:

{
  "error": "...",
  "retryable": true_or_false
}

retryable: true — The operation is in a suspended state and may be resumed automatically if retried.

retryable: false — The operation cannot be resumed, and retrying with the same x-request-id will return the same error.

NOTE: Retrying with a new x-request-id may result in a new operation, which could cause duplicates (e.g., duplicate card creation).

Important Considerations​

Always use the same x-request-id when retrying a request after a failure to ensure idempotent handling.

If a 5xx error is returned with retryable: false, avoid retrying with a new request ID unless you're certain a new operation is appropriate.

API Endpoint Idempotency Matrix​

MethodPathIdempotent
GET/v1/balancesNo
GET/v1/balancesNo
POST/v1/balancesYes
GET/v1/balances/{reference}No
PUT/v1/balances/{reference}Yes
GET/v1/balances/{reference}/cardsNo
POST/v1/balances/{reference}/blockYes
POST/v1/balances/{reference}/unblockYes
POST/v1/balances/{reference}/closeYes
POST/v1/transfersYes
POST/v1/cardsNo
PUT/v1/cards/'{reference}Yes
POST/v1/cards/'{reference}/blockYes
POST/v1/cards/'{reference}/unblockYes
POST/v1/cards/'{reference}/closeYes
POST/v1/cards/{reference}/details-linkNo
DELETE/v1/cards/{reference}/details-linkNo
GET/v1/transactionsNo
GET/v1/transactions/{reference}No