Skip to main content
Use an idempotency key to retry a run or build without acting on the website twice. A lost answer doesn’t tell you whether the website already changed; the key makes the retry safe either way.

​
Send a key with every write

Choose your own key of 1 to 200 letters, digits, _ or -; a UUID fits. Send it as the idempotency_key argument through MCP, or the Idempotency-Key header over REST.
A read may simply be repeated, so it needs no key.

​
Retry with the same key

Resend the same request with the same key. Pomerado answers the job that key already started and runs nothing again; REST answers 200 with Idempotent-Replayed: true instead of 202.
  • The same key with a different request is refused with idempotency_conflict.
  • Use a new key only when you mean a new action.
  • If the job already delivered its result, the retry answers the job with result null. Run again with a new key for a fresh result.
When you have the job’s id, don’t resubmit: wait for it.

​
Read the error

An error with retryable true, such as worker_lost, may succeed with the same request and key. Back off on repeated failures. A write that may have happened without a confirmed result fails with outcome_unknown and write_status may_have_applied. Check the website before starting another.
  • A write sent without a key whose failure may follow an accepted write carries write_possibly_accepted: true beside its error. Check for its job and the website before calling again.
  • write_status reads not_attempted, applied, not_applied or may_have_applied.
  • Every error code is in Errors.