Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What is idempotency?

An idempotent operation can be repeated multiple times without changing the result beyond the first execution. On the Arcus API, idempotency protects you from creating duplicate orders, payments, or other records when a request fails partway through (network timeout, server restart, etc.).

​
How to use it

Include the Idempotency-Key header on any POST, PATCH, or DELETE request. The value must be unique per operation — a UUID v4 is the recommended format. 
curl -X POST https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders \
  -H "Authorization: Bearer $ARCUS_API_KEY" \
  -H "Idempotency-Key: 7f3b2c4d-1e5a-4f9b-8c2d-0a1b3c5d7e9f" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

​
Replay behavior

ScenarioResponse
First request with a new keyNormal execution; response stored
Retry with the same key (within 24 hours)Original response returned immediately, no re-execution
Retry with the same key (after 24 hours)Key expired; request treated as new
Different request body with an existing key409 Conflict with code: idempotency_key_mismatch

​
24-hour replay window

Arcus stores idempotency keys and their responses for 24 hours. After that window, the key is expired and a new request with the same key is treated as a fresh operation. If your retry strategy spans more than 24 hours, generate a new key.

​
Key format

The key can be any string up to 255 characters. Best practices: 
# UUID v4 (simplest)
7f3b2c4d-1e5a-4f9b-8c2d-0a1b3c5d7e9f

# Prefixed (easier to debug in logs)
order-create-acc_01H-2024-01-15T10:30:00Z

# Client transaction ID (if you have one)
txn_import_batch_42_row_1337

​
SDK usage

All SDKs handle idempotency keys automatically for safe retries: 
// Pass explicitly
const order = await arcus.orders.create(
  { document_type: 'sales_order', account_id: 'acc_01H...' },
  { idempotencyKey: crypto.randomUUID() }
);

// Or enable auto-retry (SDK generates and manages keys)
const arcus = new Arcus({
  apiKey: process.env.ARCUS_API_KEY,
  entityId: process.env.ARCUS_ENTITY_ID,
  maxRetries: 3,
});

​
When to use idempotency keys

Use them on every POST, PATCH, or DELETE that mutates data. The most critical cases:
  • Creating orders, invoices, or payments
  • Processing refunds
  • Purchasing shipping labels
  • Posting journal entries
  • Any financial or inventory-affecting operation
GET requests are inherently idempotent and do not need a key.