Retry Oracle — Deterministic Retry and Spend Decisions

Retry Oracle

Retry Oracle is a deterministic retry-decision utility for APIs, agents, scrapers, automation pipelines, and machine-to-machine workflows.

Give it a failed operation category plus retry, time, and spending constraints. It returns one of three machine-readable decisions:

• RETRY — retry the same operation after a deterministic delay
• MUTATE — apply one explicitly authorized recovery mutation, then reassess
• ABORT — stop because retrying would be unsafe, exhausted, or unsupported

Retry Oracle does not execute operations. It only evaluates the supplied context and returns deterministic advice.

The same valid input produces the same decision and input hash.

Quick start

The default input is ready to run:

{
  "items": [
    {
      "operationType": "http_get",
      "failureCategory": "rate_limit",
      "statusCode": 429,
      "attemptNumber": 1,
      "maxAttempts": 4,
      "elapsedSeconds": 2,
      "deadlineSeconds": 120,
      "amountSpent": 0.01,
      "maxSpend": 0.1,
      "idempotent": true,
      "allowedMutations": ["refresh-auth"],
      "nextAttemptCost": 0.01,
      "retryAfterSeconds": 5
    }
  ]
}

For this example, Retry Oracle returns a deterministic RETRY decision with a five-second recommended delay.

Example output

{
  "itemIndex": 1,
  "decision": "RETRY",
  "reasonCode": "TRANSIENT_FAILURE",
  "reason": "Retry the idempotent operation after the delay, within the remaining budgets.",
  "recommendedDelaySeconds": 5,
  "selectedMutation": null,
  "remainingAttemptBudget": 3,
  "remainingSpendBudget": 0.09,
  "policyVersion": "retry-oracle:1.0.0",
  "inputHash": "sha256:...",
  "provenance": {
    "engine": "deterministic-python",
    "policyVersion": "retry-oracle:1.0.0"
  }
}

Results are written to the default Apify dataset as structured JSON.

Use cases

API retry decisions

Evaluate HTTP failures such as rate limits, timeouts, network errors, and supported server errors before another request is attempted.

Autonomous agents

Give an agent a bounded decision primitive for deciding whether a failed operation should be retried, modified, or stopped.

Scraping and automation pipelines

Prevent uncontrolled retry loops by enforcing attempt, deadline, idempotency, and spending constraints before another attempt.

Bounded machine commerce

Include current spend, maximum spend, and expected next-attempt cost so automated systems can reject retries that exceed an authorized budget.

Failure supervision

Convert heterogeneous failure conditions into a small machine-readable decision vocabulary with deterministic reason codes.

Input

Submit between 1 and 100 independent retry contexts in items.

Supported mutations:

• refresh-auth
• change-endpoint
• reduce-payload
• refresh-resource

Extra context fields are rejected. Do not submit request payloads, credentials, secrets, payment details, or personal data.

Decision policy

Retry Oracle is intentionally conservative. A non-idempotent failed operation returns ABORT. Transient failures use deterministic exponential backoff capped at 60 seconds while honoring a longer supplied retryAfterSeconds.

A retry is rejected when:

• no attempts remain
• the deadline has been exhausted
• the remaining spending budget is insufficient
• the operation is non-idempotent
• the failure is hard or unsupported
• a required mutation was not explicitly authorized
• the recommended delay would consume the remaining deadline

MUTATE never performs the mutation.

Required mutation by failure

When a failure needs a recovery mutation, Retry Oracle picks exactly one, in this order. If that mutation is listed in allowedMutations the decision is MUTATE; otherwise it is ABORT with MUTATION_NOT_ALLOWED.

Condition (first match wins)	Required mutation
failureCategory: "authentication" or statusCode: 401	refresh-auth
statusCode: 413	reduce-payload
failureCategory: "conflict" or statusCode: 409	refresh-resource
failureCategory: "not_found" or statusCode: 404	change-endpoint

These checks run only after the earlier stop rules (already succeeded, attempts, deadline, spend, non-idempotent). Other 4xx statuses (except 408, 425, 429) and invalid_input / permission_denied return ABORT HARD_FAILURE. RETRY is returned only for rate_limit, timeout, network, server_error, or status 408, 425, 429, 500, 502, 503, 504; anything else returns ABORT UNKNOWN_FAILURE.

Batch behavior

The input schema is strict. An item with an unknown extra field, a missing required field, an unsupported failureCategory, or a value of the wrong type makes Apify reject the whole run at input validation (HTTP 400, no run is created, nothing is charged). Per-item isolation applies only to items that pass schema validation but fail a runtime check: those are recorded by item index in the SUMMARY record without echoing submitted data, are not charged, and the remaining valid contexts still produce decisions.

Deterministic provenance

Each valid result contains policyVersion, SHA-256 inputHash, deterministic engine provenance, remaining retry budget, and remaining spending budget.

Retry Oracle uses deterministic Python rules and does not require an external AI model.

Billing

Retry Oracle uses Apify pay-per-event billing with the event decision-produced.

A charge occurs only after a valid decision has been written successfully. Invalid contexts are not charged. ABORT is billable because it is a completed deterministic evaluation.

Current event prices, checked October 24, 2026:

Subscription tier	Useful decision price
Free / Bronze	$0.002
Silver	$0.0018
Gold / Platinum / Diamond	$0.0016

Apify platform usage is included in these event prices; callers are not billed platform usage separately. The current pricing configuration has no Actor-start or automatic dataset-item event. The Pricing tab is authoritative for current charges.

This Actor is public, uses limited permissions, and has Standby disabled. As of October 24, 2026 the Apify Store lists it as allowed for Apify agentic payments; see Apify x402 for how that flow works. Eligibility is set by Apify and can change. A successful run or an Actor charge counter does not establish actual customer payment, a received creator payout, or positive margin.

Processing stops when the user's Apify spending limit prevents another billable decision.

Troubleshooting

The run succeeds but produces no decisions

Check the SUMMARY record in the run's key-value store.

INVALID_CONTEXT

Verify that required fields are present, failureCategory is supported, numeric values are nonnegative, idempotent is Boolean, and allowedMutations uses supported hyphenated names such as refresh-auth.

No retry was recommended

An ABORT result means the policy concluded another attempt was not authorized or safe.

Spending limit reached

Increase the run spending limit or submit fewer contexts.

Safety model

Retry Oracle is an advisor, not an executor. It never performs the retry, sends an API request, changes credentials, executes a mutation, initiates a payment, or receives operation payloads.