When to Skip a Paid API Call Safely

Knowing when to skip a paid API call is part of buying correctly, not an error path after provider selection. A useful agent must be able to return a clear no-buy result before it creates a charge, repeats work, or sends a request that cannot satisfy the task.

The stopping decision needs the same discipline as a purchase. It should name the rule, preserve the evidence available at that moment, and state what the workflow may do next. Without that record, operators cannot distinguish a deliberate stop from a broken integration, and providers receive requests that had no valid reason to run.

Stop before ranking when no provider qualifies

Start with hard requirements. A provider should not enter execution because it ranks highest among candidates that all fail the buyer's actual contract.

Apiosk accepts shared requirements such as `max_price`, `max_latency_ms`, `min_reliability`, `settlement`, and `require_all_inputs`. These conditions define eligibility. `optimize_for=price|latency|reliability|balanced` only orders the candidates that remain. The distinction matters: ranking cannot repair a failed constraint.

If every reviewed candidate exceeds `max_price`, the result is not “buy from the least expensive one.” It is “skip this purchase under the current ceiling.” If every candidate requires an input the workflow does not have, the correct result is not a speculative call. The workflow should stop or create a new, explicitly revised requirement set.

This is the operational value of requirement contracts for agent API calls. They make the no-buy boundary visible before the candidate list can influence it. Relaxing a requirement should create a new decision, not silently convert a rejected purchase into an approved one.

Skip work that has already been done

A provider can meet every selection requirement and still be the wrong call because the work is no longer necessary. The buyer-side workflow must check its own state before execution.

Common stop checks include:

• A completed result already exists for the same task and accepted inputs.
• An equivalent request is still in progress and should be joined rather than repeated.
• The upstream record changed, so the prepared request is stale.
• A retry cannot be tied to an existing attempt or a new idempotent operation.
• The deadline passed and a late result would no longer be used.
• The requested output already came from another approved source.

These checks do not measure provider quality. They answer whether the buyer still needs the unit of work. Keep them outside the provider score so a skipped call does not look like evidence that the provider performed badly.

A local task key or idempotency key can help identify repeated intent, but the implementation belongs to the buyer and provider contract. Do not assume that sending the same payload twice is safe. When the workflow cannot tell whether an earlier paid attempt completed, stopping for reconciliation can be more accurate than producing a second ambiguous charge.

Treat missing approval as a decision

Some paid calls fit within an automatic spending policy. Others require a person or another policy service to approve the exact action. The approval gate belongs before provider execution.

The request presented for approval should identify the job, selected provider, current payment terms, relevant input scope, and the rule that caused the pause. Approval for a general agent session is not necessarily approval for every later purchase. If the request changes materially, evaluate it again.

Three outcomes should remain distinct:

• Approved: the exact request may proceed under the recorded policy.
• Denied: the buyer deliberately refused this request.
• Expired or unavailable: no valid approval was obtained before the decision window closed.

All three are useful operational states. Only the first authorizes execution. A timeout must not become implicit consent, and a denial must not be hidden as a provider failure.

This boundary is especially important when the gateway's live payment terms differ from cached terms. The workflow should read the current response and review current Apiosk pricing rather than encode a permanent chain, token, or amount in routing logic.

Keep discovery leads out of paid execution

`GET /v1/discover?q=…` can return reviewed Apiosk candidates with stable `candidate_id` values and separate external x402 results in `external_candidates`. The external results are discovery leads. They are unreviewed, unmeasured, carry no `candidate_id`, and cannot chain into `/v1/compare`, `/v1/decide`, or Apiosk settlement.

If discovery returns only external leads, skip the Apiosk purchase path. Do not manufacture a candidate identifier or treat an external listing as the cheapest runner-up. A separate external review may happen under the buyer's own controls, but that is a new process with different evidence.

Reviewed candidates can move into comparison. Their relative 0–100 scores include the active weights and per-dimension contributions, while unavailable dimensions are dropped and named. Result quality and provider terms are not measured anywhere. A no-buy policy based on either factor therefore needs buyer-supplied evidence; it must not be presented as an Apiosk score.

Record a stop result that another system can use

A plain `false` value is not an audit record. It does not say which request stopped, what rule applied, or whether a revision is allowed.

Record a no-buy result with concrete fields:

• A decision identifier, workflow identifier, and timestamp.
• The immutable requirement set and its policy version.
• The candidate identifiers that were evaluated, if any.
• A machine-readable stop reason and a short operator-readable explanation.
• The evidence that triggered the stop, without sensitive request content.
• Whether the next action is end, wait, request approval, reconcile, or create a revised decision.
• A link to any earlier attempt that made a duplicate unsafe.

Keep this record separate from provider execution because no provider may have received the request. It can sit beside the audit trail for API selection, but it represents a different terminal state. A selection audit explains why one provider won. A no-buy record explains why execution never began.

Do not overwrite the stopped result if the workflow later changes its requirements and buys. Preserve both events. The sequence shows that the original contract produced no purchase and that a later contract produced a different answer.

Make the next action explicit

Stopping is useful only when the caller knows what the result permits. Each stop reason should map to a bounded next action.

Missing approval can wait for an approval response. A stale request can be rebuilt from current input. An unresolved earlier attempt can enter reconciliation. An empty eligible set can end the task or ask the buyer to revise one named requirement. A completed duplicate can reuse the accepted result.

Avoid an automatic retry for policy stops. Retrying the same candidate set under the same `max_price` will not make it affordable. Repeating an unapproved purchase will not create consent. A retry is appropriate only when the failure class and provider contract make another execution safe.

When a revised selection does produce a winner, keep rejected candidates separate from eligible runners-up. Recording agent provider decisions preserves that later choice without erasing the earlier decision to stop.

Where Apiosk fits

Apiosk supplies the provider evidence needed before a buyer decides whether to execute. `GET /v1/discover?q=…` returns reviewed candidates separately from external leads. `GET /v1/compare?candidates={id},{id}` compares price, measured latency, measured success rate, settlement, and input compatibility. `GET /v1/decide?candidates={id},{id}` returns one provider, the selection rule, exact rejection constraints, and ordered runners-up.

`POST /v1/decisions` is free and unauthenticated and records a chosen provider and rejected alternatives when a selection is made. The buyer's own control layer should retain a no-buy record when execution stops before any provider is chosen. That separation keeps Apiosk's measured selection evidence honest and keeps buyer-specific approval, duplication, and necessity rules auditable.

For providers, this means skipped traffic can be explained without inventing a performance defect. You can list your API for reviewed discovery, publish complete inputs and current terms, and reduce avoidable exclusions while the buyer remains free to make a documented decision not to call.