Skip to content

Idempotency

VRP Billing guarantees idempotent behaviour for safe retries on non-GET endpoints. Provide an Idempotency-Key header with a unique value per logical operation. Requests with the same key and identical payload within 24 hours return the original response.

Header Requirements

  • Header name: Idempotency-Key
  • Maximum length: 255 characters
  • Accepts ASCII alphanumeric characters plus - and _
  • Keys expire after 24 hours; once expired the key behaves like a new request

Supported Endpoints

Idempotency is required on the following endpoints:

  • POST /mandates
  • POST /mandates/{id}/cancel
  • POST /mandates/{id}/evidence
  • POST /payments
  • POST /payments/{id}/retry
  • POST /payments/{id}/refunds
  • POST /webhook-endpoints

Error Handling

If a subsequent request uses the same key but a different payload, the API returns 409 Conflict with code duplicate_idempotency_key. Concurrent in-flight requests with the same key return 409 Conflict with code idempotency_key_locked until the original request completes.

Best Practices

  • Generate UUIDv4 keys for simplicity and uniqueness.
  • Store idempotency keys alongside request payloads so you can resume safely after failures.
  • For retry workers, maintain a deduplicated queue that ensures the same operation is not replayed concurrently.

Examples

Creating a Payment

curl -X POST https://api.vrpbilling.com/v1/payments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b7f941e-32d7-4d9d-94b7-204573a6090a" \
  -d '{
    "mandate_id": "mandate_f9d3",
    "amount": "42.50",
    "currency": "GBP"
  }'

Cancel a Mandate Safely

curl -X POST https://api.vrpbilling.com/v1/mandates/mandate_f9d3/cancel \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: cancel-20240221"

Even if the response is interrupted, repeating the request with the same key returns the same cancellation payload without changing state multiple times.