Skip to content

Retries and idempotency

Okatana currently does not expose idempotency keys. That changes how a correct SDK should retry operations.

Default policy

GET operations retry at most two times after the initial attempt for:

429, 500, 502, 503, 504

and transport IOException failures.

Backoff is exponential, bounded, and jittered. A valid Retry-After header is preferred.

Writes

POST, PUT, PATCH, and DELETE do not retry automatically.

A request can succeed on the server and still time out before the caller sees the response. Repeating a create may therefore produce a second project, ticket, comment, document, or notification.

Reconciliation pattern

Before retrying an ambiguous create:

  1. choose a stable external marker when the API provides a searchable field;
  2. search/read for that marker;
  3. reuse the discovered resource when present;
  4. create only when no equivalent resource exists;
  5. store the returned Okatana ID immediately.

The external-tracker and CI/CD examples demonstrate this approach.

Explicit override

var options = new OkatanaRequestOptions().maxRetries(1);

This makes retries an application decision. The retry still occurs only for statuses in the configured retry policy or a transport failure.