Status and retries
Track the candidate and its transaction separately.
Candidate lifecycle
status | Meaning |
|---|---|
pending_validation, validating | Stored; awaiting or undergoing executability checks |
eligible | Passed validation; awaiting selection |
selected | Chosen; follow the separate submission.status |
not_selected | Another candidate won |
rejected, expired, stale | This candidate cannot proceed; inspect failure |
The top-level status can remain selected while its transaction progresses or fails. It is not a confirmation signal.
Submission lifecycle
submission.status | Meaning / next step |
|---|---|
pending, leased | Queued or claimed by the executor; keep polling |
submitted | Broadcast; track transaction_hash and keep polling |
reconciling | Transaction outcome is uncertain; keep polling the same candidate |
confirmed | Proposal confirmed on-chain; ordinary oracle liveness continues |
indexed | Confirmed proposal event ingested; capture its event index |
failed | Inspect failure and its resubmission guidance |
After confirmation: the bond is still at risk
confirmed and indexed describe proposal execution, not the correctness of the answer or final settlement. Continue following the oracle's liveness period, disputes, and settlement through your oracle indexer. These later events are not candidate API statuses.
If an incorrect proposal is disputed and the dispute is resolved against you, you can lose your bond. The service paying transaction gas does not remove that exposure.
Retry without creating a second authorization
Persist the exact signed payload before sending. If the connection drops or the gateway returns 502 or 504, send that same body to the same question again. Within the current request round, exact replay returns the existing candidate and status. A changed amount, deadline, nonce, or signature is not an exact replay.
A new oracle request round has a different signing context. Do not carry an old signature into a re-request. Reconcile the old candidate, then prepare again for the new round.
Read Retry-After when present; otherwise use exponential backoff with jitter. Polling every five seconds is an example, not a promised rate limit. Multiple clients behind the gateway may share an upstream IP quota. Keep concurrency bounded.
Act on terminal failures
{
"stage": "execution",
"code": "proposal_authorization_expired",
"detail": "The signed Permit2 authorization expired before broadcast.",
"retryable": true,
"can_resubmit": true,
"next_action": "Prepare and submit a new authorization with a later deadline."
}Only prepare a replacement when the existing candidate is terminal and its failure guidance allows resubmission. Recheck eligibility, request state, funding, and allowance before signing again. retryable is not permission to submit a competing payload while execution remains uncertain.
Never create a replacement simply because polling timed out or status is reconciling. A transaction might still land. Continue monitoring the saved candidate; escalate a prolonged unresolved state to the integration team with the question ID and candidate ID, never a private key or signature.