MCP Retry Policies: When to Wait, Retry, or Stop

Retrying a failed MCP request can restore a useful workflow. It can also create duplicate work, consume additional credits, or keep an unavailable service under pressure. A good retry policy begins by identifying what failed and whether another attempt can reasonably change the outcome.

For a content team, the goal is bounded recovery: wait when the service asks you to wait, correct invalid requests, preserve action identity, and stop when the outcome is uncertain. This guide provides a decision framework for Caroush integrations without treating every error as a reason to repeat the same instruction.

Classify the failure before choosing the response

Separate transport failures, authentication failures, permission failures, validation errors, rate limits, and uncertain execution outcomes. They can look similar in a conversational interface but require different actions.

The HTTP Semantics standard defines transport status behavior, including authentication challenges, unsupported methods, and service unavailability. Caroush's error reference also documents domain errors inside MCP tool results. An HTTP 200 does not guarantee that the tool succeeded.

A missing required field needs a corrected request. A missing scope needs a review of the task and grant. A temporarily unavailable service may justify a bounded later attempt. An unknown outcome requires inspection of existing work before a new mutation.

This classification should happen before an assistant rewrites the prompt. Better wording cannot restore a down endpoint or add a permission the user has not granted. A reliable AI content workflow makes the failing layer visible.

Honor explicit rate-limit guidance

The HTTP 429 specification describes Too Many Requests and allows a Retry-After header indicating how long the client should wait. The standard does not prescribe one universal quota or identity-counting method for every service.

Caroush documents retry guidance through a retry_after detail or the HTTP Retry-After header. Respect the returned information and the current service limits. Do not assume that a generic example from another API applies to this connection.

A rate limit means the system is controlling request pace. Creating new clients or parallel connections to evade that control is not an appropriate recovery strategy. Caroush documents user-shared limiting specifically so fresh client registration does not create an independent unlimited allowance.

For a batching workflow, schedule requests at a sustainable pace and avoid having several agents poll the same job independently. Reducing redundant status reads can make the workflow more responsive without increasing the permitted request volume.

Use backoff and jitter for transient failures

Backoff increases the wait between repeated attempts when a transient problem persists. Jitter adds variation so multiple clients do not all retry at the same instant. These techniques reduce synchronized bursts and give the service time to recover.

Choose bounds appropriate to the documented operation. Record a maximum attempt count or elapsed retry window, and stop with a useful status when the bound is reached. A client that silently retries forever is difficult to supervise and can hide a persistent configuration problem.

Do not let a local retry loop override a longer server-provided delay. When the response includes clear waiting guidance, treat it as part of the recovery contract. If the expected delay no longer fits the user's deadline, report that constraint rather than compressing the delay until the service rejects the request again.

A campaign handoff can remain productive while a service recovers. The editor can review supplied text or prepare a manual draft without repeatedly exercising the failed connection. Keep those parallel tasks separate from the unresolved operation.

Preserve the intended mutation across retries

For Caroush mutations, use the original UUID idempotency key and exactly the same arguments when retrying the same intended action. Changing arguments with the same key produces a documented conflict. A new key represents a new intentional request within the connection's namespace.

This matters after a timeout. The first attempt may have created the draft or queued generation even though the client did not receive the response. Issuing a fresh mutation can duplicate the effect.

Caroush documents a specific recovery for dispatch_failed: retry the identical call with the same key. It also distinguishes outcome_unknown, where existing records must be inspected before a new request. Preserve that distinction in the client's policy.

A scheduling integration needs particular care because an accepted action can create a future external delivery. Never use a new key merely to obtain a cleaner-looking response while the original schedule's state remains unresolved.

Stop on errors that require a changed decision

Some failures are not transient. An invalid enum will remain invalid after waiting. An unsupported tool will not appear because the assistant asks more insistently. A rejected browser approval should not trigger automatic replacement requests.

When the task needs a corrected argument, explain the correction and follow the service's rules for a new intended action. When additional permission is genuinely needed, use the documented authorization flow after reviewing whether that capability belongs in the task.

Plan eligibility and credits also require a separate decision. A scope does not bypass subscription rules, and a delay does not necessarily replenish generation credits. Do not present an endless retry loop as a way to solve an account constraint.

Your editorial approval process should remain authoritative when a user denies an action. A denied publication is a decision to stop, not a failed network request to recover automatically.

Poll progress without generating replacement work

Polling asks for the current state of an accepted operation. Retrying repeats a request to perform an action. Confusing them can turn a slow generation job into several jobs.

When Caroush returns an operation or native resource reference, use the documented status tools. Poll gradually and preserve the original references. The error guide gives illustrative pacing, but your client should honor current limits and returned guidance rather than treating a blog example as a permanent timing rule.

If a status read fails transiently, retrying that read is different from resubmitting the original generation. Keep the two policies separate. The assistant should say that it cannot currently confirm progress, not conclude that the content must be regenerated.

Also stop polling when the operation reaches a terminal state or when your monitoring responsibility ends. Repeatedly checking a finished job wastes request capacity and can make an otherwise small workflow look unusually active to the limiter.

Work through a launch-day example

A team requests one draft for a workshop announcement. The first request returns a validation error because the client included an unsupported field. The next step is to remove or correct that field under the documented contract, not to wait and send the same invalid request repeatedly.

Later, an accepted generation request returns an operation reference. A status read encounters a rate limit. The client waits according to the response, then resumes checking the same operation. It does not create a second generation request.

Finally, the publication request reaches an approval boundary. The reviewer declines because the date changed. That stops the action. The editor prepares a corrected draft and obtains renewed intent before creating a new reviewable publication request.

These three situations all interrupt progress, but they are not the same kind of failure. A useful client policy produces three different responses: correct the contract, wait before reading again, and respect the user's decision.

Report the recovery state clearly

After bounded recovery, tell the user whether the original action completed, remains pending, failed with a known cause, or has an unknown outcome requiring inspection. Include the relevant nonsecret request reference and the next responsible owner when a handoff is needed.

Do not summarize a retry sequence as success merely because the last HTTP exchange returned a response. Inspect the actual tool and resource states. Conversely, do not report a normal queue delay as a permanent failure before checking the operation.

A good retry policy makes the workflow quieter and more predictable. It avoids unnecessary requests while preserving the user's intended action. That is a better measure of robustness than how aggressively an assistant can keep trying after something goes wrong.