Guides

Idempotency and safe retries

A KSeF invoice is a legal document with a gapless number, so a duplicate is worse than a delay. Two mechanisms make sure every order yields exactly one invoice.

Why it matters

You sent an order and the connection dropped before the answer. Was the invoice created? Without idempotency a retry could issue a second invoice with the next number and send it to KSeF. With idempotency you retry without worry and get the same invoice.

Two layers of protection

The Idempotency-Key header on every POST. We store the first response for 24 hours and return it for the same key and the same body.
The order's natural key. Regardless of the header, one order.external_id yields one invoice and one refund.external_id one correction. Sending the order again returns the existing invoice with 200 instead of 201, also after 24 hours.

How Idempotency-Key works

Situation	Response
First request with a key	The normal response, e.g. `201`
Same key and same body within 24 h	The same response plus `Idempotent-Replayed: true`
Same key, different body	`409 idempotency_key_reused`
Empty key or longer than 255 characters	`400 idempotency_key_invalid`

POST /v1/invoices

curl -X POST https://app.ksefshop.pl/v1/invoices \
  -H "Authorization: Bearer $KSEF_API_KEY" \
  -H "Idempotency-Key: order-SO-1001" \
  -H "Content-Type: application/json" \
  -d '{
  "order": {
    "external_id": "SO-1001",
    "number": "1001",
    "paid_at": "2026-10-19T09:13:05Z",
    "currency": "PLN",
    "payment_method": "card",
    "buyer": {
      "nip": "5260250274",
      "name": "Testowa Firma sp. z o.o.",
      "address_line1": "ul. Prosta 20",
      "address_line2": "00-850 Warszawa",
      "email": "jan@example.com"
    },
    "lines": [
      {
        "name": "Kubek ceramiczny 350 ml",
        "sku": "KUB-350",
        "quantity": 2,
        "unit_price": "49.00",
        "vat_rate": "23"
      },
      {
        "name": "Książka: Podstawy księgowości",
        "sku": "KS-001",
        "quantity": 1,
        "unit_price": "59.90",
        "discount": "9.90",
        "vat_rate": "5"
      }
    ],
    "shipping": [
      {
        "name": "Kurier InPost",
        "price": "15.99",
        "vat_rate": "23"
      }
    ]
  }
}'

<?php
$payload = [
    'order' => [
        'external_id' => 'SO-1001',
        'number' => '1001',
        'paid_at' => '2026-10-19T09:13:05Z',
        'currency' => 'PLN',
        'payment_method' => 'card',
        'buyer' => [
            'nip' => '5260250274',
            'name' => 'Testowa Firma sp. z o.o.',
            'address_line1' => 'ul. Prosta 20',
            'address_line2' => '00-850 Warszawa',
            'email' => 'jan@example.com',
        ],
        'lines' => [
            [
                'name' => 'Kubek ceramiczny 350 ml',
                'sku' => 'KUB-350',
                'quantity' => 2,
                'unit_price' => '49.00',
                'vat_rate' => '23',
            ],
            [
                'name' => 'Książka: Podstawy księgowości',
                'sku' => 'KS-001',
                'quantity' => 1,
                'unit_price' => '59.90',
                'discount' => '9.90',
                'vat_rate' => '5',
            ],
        ],
        'shipping' => [
            ['name' => 'Kurier InPost', 'price' => '15.99', 'vat_rate' => '23'],
        ],
    ],
];

$ch = curl_init('https://app.ksefshop.pl/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
        'Idempotency-Key: order-SO-1001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo var_export($data['id'], true), ' ', var_export($data['status'], true), PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
    "Idempotency-Key": "order-SO-1001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      external_id: "SO-1001",
      number: "1001",
      paid_at: "2026-10-19T09:13:05Z",
      currency: "PLN",
      payment_method: "card",
      buyer: {
        nip: "5260250274",
        name: "Testowa Firma sp. z o.o.",
        address_line1: "ul. Prosta 20",
        address_line2: "00-850 Warszawa",
        email: "jan@example.com",
      },
      lines: [
        {
          name: "Kubek ceramiczny 350 ml",
          sku: "KUB-350",
          quantity: 2,
          unit_price: "49.00",
          vat_rate: "23",
        },
        {
          name: "Książka: Podstawy księgowości",
          sku: "KS-001",
          quantity: 1,
          unit_price: "59.90",
          discount: "9.90",
          vat_rate: "5",
        },
      ],
      shipping: [
        { name: "Kurier InPost", price: "15.99", vat_rate: "23" },
      ],
    },
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.id, data.status);

import os
import requests

resp = requests.post(
    "https://app.ksefshop.pl/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
        "Idempotency-Key": "order-SO-1001",
    },
    json={
        "order": {
            "external_id": "SO-1001",
            "number": "1001",
            "paid_at": "2026-10-19T09:13:05Z",
            "currency": "PLN",
            "payment_method": "card",
            "buyer": {
                "nip": "5260250274",
                "name": "Testowa Firma sp. z o.o.",
                "address_line1": "ul. Prosta 20",
                "address_line2": "00-850 Warszawa",
                "email": "jan@example.com",
            },
            "lines": [
                {
                    "name": "Kubek ceramiczny 350 ml",
                    "sku": "KUB-350",
                    "quantity": 2,
                    "unit_price": "49.00",
                    "vat_rate": "23",
                },
                {
                    "name": "Książka: Podstawy księgowości",
                    "sku": "KS-001",
                    "quantity": 1,
                    "unit_price": "59.90",
                    "discount": "9.90",
                    "vat_rate": "5",
                },
            ],
            "shipping": [
                {"name": "Kurier InPost", "price": "15.99", "vat_rate": "23"},
            ],
        },
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data["id"], data["status"])

Choosing a key

The key describes the operation, not the attempt. Good keys are order-SO-1001 for an invoice and refund-RF-1 for a correction. A random UUID is fine too if you generate it once and store it with the order. A new UUID per attempt defeats the purpose.

What to retry

Network error or timeout: retry with the same key.
429 rate_limited: wait as many seconds as Retry-After says.
5xx: retry with exponential backoff (1, 2, 4, 8 s...).
Other 4xx: do not retry, fix the request. The exception is 409 pdf_not_ready when downloading the PDF.

Retrying with the same key

# --retry repeats on network errors, 429 and 5xx and honours Retry-After
curl --retry 5 --retry-connrefused -X POST https://app.ksefshop.pl/v1/invoices \
  -H "Authorization: Bearer $KSEF_API_KEY" \
  -H "Idempotency-Key: order-SO-1001" \
  -H "Content-Type: application/json" \
  -d @order-SO-1001.json

<?php
function create_invoice(array $order): array
{
    $key = 'order-' . $order['external_id']; // the same key on every attempt
    for ($attempt = 0; $attempt < 5; $attempt++) {
        $ch = curl_init('https://app.ksefshop.pl/v1/invoices');
        $retryAfter = 0;
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST => 'POST',
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
                'Idempotency-Key: ' . $key,
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode(['order' => $order], JSON_UNESCAPED_UNICODE),
            CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$retryAfter) {
                if (stripos($line, 'Retry-After:') === 0) {
                    $retryAfter = (int) trim(substr($line, 12));
                }
                return strlen($line);
            },
        ]);
        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);
        if ($body !== false && $status < 500 && $status !== 429) {
            $data = json_decode($body, true);
            if ($status >= 400) {
                throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
            }
            return $data; // 201 new, 200 existing or replayed
        }
        sleep($retryAfter ?: 2 ** $attempt);
    }
    throw new RuntimeException('KSeF Faktury API unavailable, retry later');
}

async function createInvoice(order) {
  const key = `order-${order.external_id}`; // the same key on every attempt
  for (let attempt = 0; attempt < 5; attempt++) {
    let res = null;
    try {
      res = await fetch("https://app.ksefshop.pl/v1/invoices", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
          "Idempotency-Key": key,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ order }),
        signal: AbortSignal.timeout(30_000),
      });
    } catch {
      // network error or timeout: retry
    }
    if (res && res.status < 500 && res.status !== 429) {
      const data = await res.json();
      if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
      return data; // 201 new, 200 existing or replayed
    }
    const wait = Number(res?.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error("KSeF Faktury API unavailable, retry later");
}

import os
import time
import requests


def create_invoice(order: dict) -> dict:
    key = f"order-{order['external_id']}"  # the same key on every attempt
    for attempt in range(5):
        resp = None
        try:
            resp = requests.post(
                "https://app.ksefshop.pl/v1/invoices",
                headers={
                    "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
                    "Idempotency-Key": key,
                },
                json={"order": order},
                timeout=30,
            )
        except requests.RequestException:
            pass  # network error or timeout: retry
        if resp is not None and resp.status_code < 500 and resp.status_code != 429:
            data = resp.json()
            if not resp.ok:
                raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
            return data  # 201 new, 200 existing or replayed
        retry_after = resp.headers.get("Retry-After") if resp is not None else None
        time.sleep(int(retry_after) if retry_after else 2**attempt)
    raise RuntimeError("KSeF Faktury API unavailable, retry later")

Idempotency covers every POST: /v1/invoices, /v1/invoices/{id}/corrections and /v1/webhook_endpoints. GET and DELETE requests are idempotent by nature.