Idempotency

Edge automatically handles idempotency using Request IDs, which serve as the idempotency keys and are included in the request header.

​

How Idempotency Works with Request IDs

Edge simplifies idempotency by requiring the use of Request IDs in every request. These IDs, which are part of the request header, uniquely identify each API call. If a request is retried with the same Request ID, Edge will return the original result without reprocessing the request.

​

Request Header Example

When making a request, include the requestId header:

POST /transactions HTTP/1.1
Host: api.withedge.co
Content-Type: application/json
Authorization: Bearer {Base64 encoded client+secret}
X-Encryption-Type: AES256
requestId: unique-requestId-12345

Edge uses the requestId as the idempotency key, ensuring that even if the same request is sent multiple times, it will only be processed once.

Response (First Request):

{
  "data": {
    "transactionId": "abc123",
    "status": "success",
    "amount": 10000,
    "currency": "USD"
  },
  "message": "Transaction processed successfully",
  "status": "success",
  "statusCode": 200
}

Response (Retry with Same Request ID):

{
  "data": {
    "transactionId": "abc123",
    "status": "success",
    "amount": 10000,
    "currency": "USD"
  },
  "message": "Idempotent request - transaction already processed",
  "status": "success",
  "statusCode": 200
}

In the retry, the same result is returned without reprocessing the request.

​

Why Use Request IDs?

Request IDs in Edge automatically handle idempotency, which reduces the chance of:

• Duplicate charges for payments.
• Multiple customer creations when retrying an operation.
• Inconsistent data updates caused by retries during timeouts or network issues.

By using Request IDs, you ensure that even in the case of network failures, retries, or delays, Edge will handle your requests safely and return consistent results.

​

Best Practices for Using Request IDs

Here are some best practices to follow when using Request IDs in your Edge API requests:

• Generate Unique Request IDs:
  Each Request ID should be unique to the operation. Using a UUID or a unique identifier tied to the action (e.g., unique-payment-id-123) is a good approach.

• Reuse Request IDs for Retries:
  If a request times out or fails, you can safely retry the request using the same Request ID. Edge will return the original response, ensuring the action is performed only once.

• Monitor and Log Request IDs:
  Keep track of Request IDs in your logs. This helps with debugging and tracking request history, especially when retries or failures occur.

​

When to Use Idempotency with Request IDs

Idempotency via Request IDs is particularly useful for operations that create or modify resources. Some common use cases include:

1. Payments:
   Avoid duplicate transactions when retrying payment requests.

2. Customer Creation:
   Ensure a customer is only created once, even if the request is retried due to a timeout or error.

3. Order Processing:
   Prevent orders from being placed multiple times when network issues occur.

4. Data Updates:
   Safeguard updates to user profiles or sensitive data, ensuring each update is applied only once.

​

FAQs

​

1. How long does Edge store Request IDs?

Edge stores Request IDs for a limited time (usually 24 hours). After this period, the same Request ID will no longer ensure idempotency, and a retry may be processed as a new request.

​

2. What happens if I use the same Request ID for different operations?

Request IDs are specific to each API operation. If you reuse the same Request ID across different operations (e.g., creating a payment and updating a user), Edge will process each operation separately.

​

3. Can I disable idempotency for certain requests?

No, Request IDs are automatically required and managed by Edge for all operations that benefit from idempotency, such as payments and resource creation.

Idempotency with Edge helps ensure that your API operations are performed consistently, even when dealing with retries or network issues. By using Request IDs in your requests, you can safeguard your transactions and updates against duplication.