Overview

The API supports idempotent request processing to allow safe retries of requests without accidentally performing the same operation multiple times. If a request has already been processed successfully, subsequent requests with the same idempotency key will not be reprocessed. Instead, the original response is returned.

Idempotency is particularly useful for handling network timeouts, connection errors, or uncertain delivery states.

Supported HTTP Methods

Sending an idempotency key with GET or DELETE requests has no effect.

Using Idempotency Keys

To enable idempotent processing, include the following HTTP header:

idempotency-key: <unique-value>

Requirements

• Maximum length: 64 characters

• Recommended format: UUID

• Must be globally unique across all requests

• Reusing the same key across different transaction types may cause unexpected behavior

Best Practices

• Generate a new idempotency key for each logical transaction.

• If you do not receive a response (for example, due to a timeout), retry the request using the same idempotency key.

• Do not reuse idempotency keys for different payloads.

Idempotency Key Retention

• Idempotency keys are persisted for 24 hours.

• Requests sent with the same key after 24 hours are treated as new requests.

Response Behavior

Successful Replay

If a request has already been executed:

• The original response is returned.

• Response header includes:

  Idempotent-Replayed: true

• Any original 201 Created response is returned as 200 OK.

Error Handling and Edge Cases

Request Hash Mismatch

If the same idempotency key is reused with a different request payload:

Response

• HTTP Status: 409 Conflict

{
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "type": "IDEMPOTENCY_ERROR",
    "details": [
      "Idempotency-Key exists and the request does not match"
    ],
    "message": "Idempotency Key Reused"
  }
}

Original Request Still Processing

If the original request is still waiting on a downstream response (for example, the client retries immediately after a network error):

Response

• HTTP Status: 429 Too Many Requests

{
  "error": {
    "code": "WAITING_FOR_RESPONSE",
    "type": "IDEMPOTENCY_ERROR",
    "message": "Waiting For Original Response"
  }
}

Action Required

• Retry with exponential backoff.

• Treat 429 the same as a 500 error.

Original Response Never Recorded (Outside Timeout)

If the idempotency key exists but no response was ever recorded due to an internal system error:

Response

• HTTP Status: 500 Internal Server Error

• Response Header:

  Idempotent-Replayed: true

{
  "error": {
    "code": "NO_RESPONSE",
    "details": ["Resend with new Idempotency-Key"],
    "type": "IDEMPOTENCY_ERROR",
    "message": "Original Response Never Received"
  }
}

Action Required

• Generate a new idempotency key and resend the request.

Querying by Idempotency Key

If you no longer want the transaction to execute and only wish to retrieve the result:

• Use the query endpoint to search by idempotency-key.

Query Results

• Empty result: Transaction was never received.

• Transaction details: Request was processed successfully.

The query endpoint returns the same responses described above for timeout-related scenarios.

Idempotency Scenarios

Scenario 1: Unique POST Request

• Status: 201 Created

Scenario 2: Duplicate POST (Matching Payload)

• Status: 200 OK

• Header:

  Idempotent-Replayed: true

Scenario 3: Duplicate POST (Different Payload)

• Status: 409 Conflict

• Error: IDEMPOTENCY_KEY_REUSED

Scenario 4: Duplicate POST (Still Processing)

• Status: 429 Too Many Requests

• Error: WAITING_FOR_RESPONSE

• Retry with backoff

Scenario 5: Duplicate POST (No Response Recorded)

• Status: 500 Internal Server Error

• Header:

  Idempotent-Replayed: true

• Retry with a new idempotency key