Idempotency

Safely retry requests without creating duplicate posts. All POST endpoints accept an optional Idempotency-Key header to prevent duplicate operations on network retries.

How it works

When you include an Idempotency-Key header in a POST request, the API tracks that key and ensures the operation only happens once:

First request

The post is created normally. The response is cached against the idempotency key for 24 hours.

Retry with same key + same body

The cached response is returned immediately. No duplicate post is created.

Retry with same key + different body

Returns 409 Conflict with error code idempotency_conflict. You cannot reuse a key with a different request body.

Sending an idempotency key

Include the Idempotency-Key header with a unique string value on any POST request:

curl -X POST https://schedulala.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from Schedulala!",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "acc_your_id"
      }
    ],
    "publishNow": true
  }'

Rules

Rule	Details
Format	Keys must be unique strings. UUIDs (v4) are recommended.
Expiration	Keys expire after 24 hours. After expiration, the same key can be reused.
Scope	Keys are scoped to the API key. Different API keys can use the same idempotency key without conflict.
Applicable methods	Only applies to `POST` endpoints. `PATCH` and `DELETE` are inherently idempotent and don't need this header.

Handling conflicts

If you send the same idempotency key with a different request body, the API returns a 409 Conflict error:

409 Conflict

{
  "success": false,
  "error": {
    "code": "idempotency_conflict",
    "message": "This idempotency key has already been used with a different request body",
    "documentation": "https://docs.schedulala.com/api/idempotency"
  }
}

Important: A 409 conflict means the key was already used for a different operation. Generate a new idempotency key for each unique operation. Never reuse keys across different requests.

Best practices

•

Generate a UUID v4 for each unique operation. This guarantees uniqueness without coordination. Most languages have built-in UUID generators.

•

Store keys alongside your retry logic. When a request fails due to a network error, retry with the same idempotency key to avoid creating duplicates.

•

Handle 409 conflicts gracefully. If you receive a conflict, it means the key was already used for a different request. Generate a new key and decide whether to retry.

•

Don't generate keys from request content. Use random UUIDs rather than hashing the request body. Content-based keys can collide if you intentionally send the same content twice.

Tip: Idempotency keys are especially useful when building queue-based systems where the same job might be processed more than once. Include the job ID as the idempotency key to guarantee exactly-once post creation.

Posts API — Create, schedule, and manage posts across platforms Error Handling — Error codes, response format, and retry strategies Rate Limits — Request limits, burst allowances, and backoff strategies