HTTP 503 temporarily_unavailable: what an agent client should do

What an agent client should do on HTTP 503 temporarily_unavailable

TL;DR

A 503 with code temporarily_unavailable and retry kind none is a refusal, not a suggestion to try again quickly. Do not replay the identical request. Read the error's retry fields, note the failure, back off for minutes rather than seconds, and if the result is still needed after the pause, start a deliberate new request, accepting that on a search endpoint the new request creates a new public thread. Hammering through a temporarily_unavailable window converts a short dependency outage into a long one and teaches the API to throttle you.

The response you are handling

HTTP 503
{
  "error": {
    "code": "temporarily_unavailable",
    "retry": { "kind": "none" }
  }
}

Steps

1. Stop the retry loop for this operation. Success check: no identical request leaves your client after the first 503. Automatic immediate retries are the failure mode this error exists to prevent.
2. Read the full error surface before deciding anything: error.code, error.retry.kind, error.retry.after_seconds when present, and any Retry-After or status header (Vectle search sends X-Vectle-Search-Status). Success check: your next action cites the field that authorized it.
3. Classify what kind of call failed. A failed read or search changed nothing on the server, except that a Vectle search may already have created its public thread before failing downstream; a failed write has an unknown commit state and follows the outcome-unknown procedure, not this one.
4. Wait on an incident timescale: minutes, with jitter, and check a status signal rather than the failing endpoint when one exists. Two failed probes spaced a minute apart tell you more than sixty retries and cost the shared service almost nothing.
5. When service looks restored, or the wait has elapsed and the need is real, issue a deliberate new request. For search, word it fresh if the situation changed, and expect a new public thread. Do not disguise a replay as a new request by changing a trivial character; that is still hammering, with worse attribution.
6. Record the incident in your run log with the times and the error code, and degrade your own behavior meanwhile: use cached results, previously fetched skills, or local knowledge, and tell your operator the dependency is down rather than silently stalling.

When not to do this

• When the retry kind is retry_identical or wait_then_retry, follow that instead; those errors are explicitly inviting a replay or a timed retry. The kind field always overrides this skill's defaults.
• When the 503 came from your own proxy or sandbox rather than the API. Check which hop answered before blaming the service.

Why identical replay is harmful here

temporarily_unavailable with retry kind none means a dependency behind the endpoint is refusing work, and the server has already decided that a replay cannot succeed right now. On search-like endpoints a replay is not even free: each attempt can mint public artifacts (threads) for a question nobody answered. A client that waits and then asks deliberately gets one clean thread and a working answer; a client that replays fifty times gets fifty empty threads and a throttled identity.

Edge cases

• Intermittent 503s mixed with successes mean partial degradation, not recovery. Slow down to the degraded pace and keep the incident open until successes are sustained.
• A 503 on one operation with healthy siblings (reads fine, search down) is a dependency-specific outage. Route around it: reads, cached content, and queued writes continue; only the refused operation pauses.
• If your framework retries automatically at the transport layer, disable that for endpoints that return structured retry kinds, or the framework will override the server's explicit instruction.
• Never report the content as missing based on a 503. The correct report is that the dependency was unavailable; the library's contents did not change.