Documentation

When is a retry safe?

A retry is only safe when running the task again cannot repeat a side effect that has already happened. Everything on this page follows from that one question: will a second run do something twice?

A pipeline that replaces a table on each run is usually safe to repeat. A pipeline that appends rows, posts a payment, sends a notification or drops and recreates an object may not be, even when it looks idempotent from the schedule. The task's own code decides this, not the platform and not Polysync.

Classes where a retry usually helps

  • Transient platform errors. The service reported a momentary fault and the same request is expected to succeed shortly after.
  • Capacity and throttling. The platform declined work because a limit was reached, not because anything was wrong with the request.
  • Locks and deadlocks. Another process held a database object and the task was chosen as the victim. Repeating it once the other work has finished is normal.
  • Startup races. A dependency was not quite ready when the run began.

Even in these classes, repeating a run that partly executed can still duplicate work. If a run touched data before failing, treat it as unsafe until you know the task tolerates a repeat.

Classes where a retry makes things worse

  • Schema drift and data errors. The same input produces the same failure, and each attempt may load part of the data again.
  • Permissions and credentials. A retry cannot fix an expired secret or a missing role, and repeated attempts can lock an account or trigger an alert.
  • Missing or moved files. The input is absent, so every attempt fails the same way.
  • Configuration errors. A wrong parameter, a renamed pipeline or a disabled item will fail identically until a person changes it.
  • Cancelled and deliberate stops. Repeating a run someone stopped on purpose defeats the stop.

Why a retry can make things worse

  • Duplicate writes. An append or an insert without a key check runs twice.
  • Partial loads. A run that failed halfway may leave a table in a state the next attempt cannot read.
  • Repeated notifications or downstream triggers. A successful side effect followed by a failure looks like a failure to the retry, and the side effect happens twice.
  • Cost. Every retry is a real run on the platform and, for marketplace plans, a real task run.

How retries interact with everything else

  • The task's own retry settings decide what Polysync retries on its own today. They apply to failures of the task, not to runs someone cancelled.
  • Contention profiles decide when a run may start. A retry that arrives while another run holds the profile's lock waits, which is usually what you want.
  • Quiet hours. The agent's retry policy respects your organisation's quiet hours once agent retries arrive, so a retry asked for overnight waits rather than waking the platform.
  • The agent's retries, from level 2, are additional and separate. They are offered only for classes the tenant has authorised, they never exceed the level's limits, and a person approves them at level 2. Turning the agent off stops them immediately.

How to stop retries

  • Turn the task's retry setting down or off.
  • Write an agent rule that forbids retries. A rule can apply to the organisation, a platform, a job or a task, and a Never in a broader scope always wins over an Allowed in a narrower one.
  • Switch the agent off, revoke its standing authorizations or lower its authorization level on the agent card.
  • Turn the organisation's AI features switch off, which stops all agent activity at once.
  • Cancel the run. A cancelled run is not retried.

An agent rule is an instruction with a recorded author and scope, not a note in a prompt: the dashboard shows conflicts between rules, and the enforcement reads the structured policy rather than the free text. See The AI Monitoring Agent.