Idempotency and Retries

Every POST, PATCH, and DELETE operation requires an Idempotency-Key between 8 and 255 characters.

Idempotency-Key: erp-order-1001-create

Replay Rules

• Same key, operation, environment, and canonical request returns the stored response.
• A replay includes Idempotency-Replayed: true.
• Reusing the key with a different request returns 409 idempotency_key_reused.
• Concurrent duplicates produce one business side effect.
• Retryable failures can re-enter processing with the original key.

For project creation, a retry with the same key and request returns the original logical result instead of creating a second project.

Choosing Keys

Use a durable business operation identifier or stored UUID. Do not use only a timestamp. Keep the key with the originating ERP/CMS record and reuse it only for retries of that exact operation.

Retry Policy

Retry network failures, 429, and problems explicitly marked retryable: true. Use exponential backoff with jitter and honor Retry-After. Do not retry an unchanged authentication, authorization, validation, or invalid-state failure.

Related Reference

• Errors
• Rate limits
• Create a project