Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

To perform an idempotent request, provide an Idempotency-Key header with the request.

Zoneless saves the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeds or fails. Subsequent requests with the same key return the same result, including 500 errors.

A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Concurrent requests

If a request is already being processed with the same idempotency key, the API returns a 409 Conflict error. Wait briefly and retry — the original request will complete and subsequent retries will return the cached response.

Which requests accept idempotency keys

All POST requests accept idempotency keys. Don't send idempotency keys in GET and DELETE requests because they have no effect. These requests are idempotent by definition.

Idempotent request

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const account = await zoneless.accounts.create(
  {
    type: 'express',
    country: 'US',
    email: 'seller@example.com',
  },
  {
    idempotencyKey: 'KG5LxwFBepaKHyUD',
  }
);