Can You Just
API v1 · Documentation navigation

DEVELOPER DOCUMENTATION / API v1

Safe retries

Use Idempotency-Key receipts for 24-hour retries, understand canonical JSON identity and reconcile external side effects.

One logical operation, one key

An Idempotency-Key identifies a retryable API operation for a successful 24-hour receipt within an organisation and API client. Persist the key and exact intended request before sending. If the response is lost, reuse that key for the same operation rather than creating a duplicate note, request or lease outcome.

Keys are 1–100 characters from a-z A-Z 0-9 . _ : -. Keys are required for claim acquire/renew/release, Incoming actions and external evaluation. Task PATCH, actual-effort replacement, notes and assistance creation accept optional keys. Keys belong to the client, not an individual rotating credential.

Idempotency-Key: example-note-001

What makes a retry equivalent?

Operation and resource ID participate in request identity. Canonical JSON sorts object properties recursively, so reordered object members are equivalent. Array order, changed scalar values/types and meaningful string whitespace remain significant. Duplicate member names, including case variants, are rejected; they are not a supported way to override a value.

{"title":"Prepare release notes","estimatedMinutes":90}
{"estimatedMinutes":90,"title":"Prepare release notes"}

Reusing a key for a different body, operation or target returns 409 idempotency_conflict. A failed transaction leaves no successful receipt. Receipt retention is 24 hours, not permanent deduplication.

Safe retry pattern #

  1. Read the current task/Incoming state and retain its appropriate precondition.
  2. Persist one new key together with operation, target and body.
  3. Send the request with If-Match and claim token when required.
  4. On uncertain transport outcome, retry the same logical request/key. Keep If-Match syntactically valid; do not change the business payload to force replay.
  5. Authorization, current scope, ownership and client/resource state are still checked on replay. A receipt is not an authorization bypass.
  6. Inspect the recovered result. A recovered lease expiry may already be past.
  7. After success, read fresh state before deciding the next logical operation and creating its new key.

A successful receipt can be returned before checking a now-stale planning version. Without a key, a successful write normally makes the old If-Match stale; re-reading and blindly resending an append with a new ETag can duplicate work.

Retry · External effects need reconciliation

A CYJ receipt does not prove exactly-once execution in your external system. After uncertain execution, inspect the external result and recorded CYJ state before repeating effects. Never treat a new key as permission to run an uncertain external action again.

Read concurrency, claim expiry and error recovery. Existing installations moving from the earlier pre-freeze retry format should follow their upgrade/cutover guidance; this page describes the frozen v1 contract.