Retries, idempotency, and ambiguous outcomes

The public v1 contract does not define a general idempotency-key header. X-Request-ID is correlation metadata only.

Retry decision

Retry matrix

Situation	Automatic retry	Required behavior
`GET` timeout or transient 5xx	Usually safe	Use bounded exponential backoff and a retry budget
`429`	Yes, bounded	Honor `Retry-After` before the next attempt
`400`, `401`, `403`, `406`, `413`, `415`, `422`	No	Correct request, credential, scope, media type, or data
`409`	No blind retry	Re-read current resource and resolve the conflict
Create request timeout	No blind retry	Search or reconcile before another create
Order decision timeout	No blind retry	Re-read the order and compare current status
Patch timeout	No blind retry	Re-read resource fields before deciding on another patch
Attachment upload timeout	No blind retry	Re-read incident state and available attachment result where exposed
Binary download `502`/`503`/`504`	Conditional	Retry download with backoff; do not treat partial data as complete

Backoff example

attempt 1: immediate
attempt 2: 1 second + jitter
attempt 3: 2 seconds + jitter
attempt 4: 4 seconds + jitter
stop when the retry budget is exhausted

Use Retry-After as the minimum delay for 429 responses.

Reconciliation patterns

Employee create

Store a stable source identifier such as employeeNumber.
After a timeout, search by the stable source identifier before creating again.
Treat a duplicate response as a reconciliation signal, not as a transient failure.

Order decision

Read the order immediately before the decision.
After a timeout, read it again.
If the status already reflects the decision, record success locally.
If the order is still eligible, decide whether a controlled replay is appropriate.

Patch

Read the current resource.
Compare the fields owned by the integration.
Patch only fields that still differ.

Operational rule

Never retry a write solely because the client did not receive a success response. A network timeout can occur after JobHandy has persisted the mutation.

Get Started

Architecture & Concepts

Integration Guides

Operations

Retries, idempotency, and ambiguous outcomes

Retry decision

Retry matrix

Backoff example

Reconciliation patterns

Employee create

Order decision

Patch

Operational rule

​Retry decision

​Retry matrix

​Backoff example

​Reconciliation patterns

​Employee create

​Order decision

​Patch

​Operational rule

Retry decision

Retry matrix

Backoff example

Reconciliation patterns

Employee create

Order decision

Patch

Operational rule