Reference

Retries and idempotency

How to retry any call without clicking twice or paying twice.

Networks drop replies. The rule is simple: send an Idempotency-Key on every POST, and resend with the same key when a reply is lost.

Code
curl -X POST https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/click \
  -H "Authorization: Bearer $KUBI_API_KEY" \
  -H "Idempotency-Key: 2f1d3c4b-8a9e-4f60-b1c2-d3e4f5a6b7c8" \
  -H "Content-Type: application/json" \
  -d '{"x": 450, "y": 280}'

What happens on a resend

Situation	You get
First request finished	The stored reply, with `Idempotent-Replayed: true`. For actions: the stored results and a fresh screenshot. Never a second click.
First request still running	`409 IDEMPOTENCY_KEY_IN_USE`; try again shortly
Same key, different body	`422 IDEMPOTENCY_KEY_REUSED`; that is a bug in the caller

Keys are kept 24 hours for screens and power, 10 minutes for actions and commands. The SDK and the MCP server always send one.

Reading an error before retrying

Every error says whether a retry can help and whether anything happened:

retryable: true: send it again after retry_after seconds.
outcome: not_applied: nothing ran. Safe to fix and resend.
outcome: unknown: it may have run (for example the screen restarted mid-action, 504 OUTCOME_UNKNOWN). Take a screenshot and look before acting again.

STALE_OBSERVATION is not retryable either: the screen changed since you looked, so take a new screenshot and decide again.

CONTROL_HELD is not retryable as it stands: a person has control of the screen and nothing ran. Wait retry_after seconds, then take a new screenshot and decide again.

Errors Limits, lists and versions