Skavio Agent Tools: handle a 503 without duplicate job charges
Skavio Agent Tools documents a useful recovery safeguard: reusing a submission’s idempotency key does not create another job or charge twice. The practical task is to preserve that identity when something goes wrong. After a 503, check the existing job, retry deliberately and reconcile its credit reservation—rather than treating an uncertain response as permission to start again.
1. A 503 is not a billing verdict
Under [HTTP semantics](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.4), 503 Service Unavailable means the responding server is temporarily unable to handle the request, for example because of overload or maintenance. Skavio’s documentation classifies 503 as temporary unavailability. It does not establish that every such response originates with an upstream provider. The status alone does not tell you whether a processing job exists, whether work has started or what happened to its credit reservation. Keep three situations separate:
- Submission returned 503: establish whether the intended job was accepted before creating anything new.
- An accepted job later failed: inspect its processing outcome and credit records.
- A status lookup returned 503: the lookup failed; that does not establish that the underlying job failed.
2. Persist the intended run before sending it
The [Agent Tools API documentation](https://getskavio.com/agent-tools/docs.html) specifies POST /agent-tools/api/jobs with tool, arguments and an idempotency_key in the JSON body. Before submission, persist that key alongside the exact intended input in your own application. The key should identify one intended processing run—not one HTTP attempt. Generating a fresh key inside a retry loop defeats the documented duplicate-submission protection. Do not change the arguments while reusing the original key: the cited documentation does not establish how changed-payload conflicts are handled.
- Store the company context, selected tool, arguments and stable idempotency key before submission.
- Keep credentials out of request logs and avoid copying sensitive input into debug logs. Retain only the operational information needed for recovery.
- Record the response and timestamp. A documented 202 response with a queued state means acceptance, not completion.
3. Look up the original key before replaying
After an ambiguous submission response, wait according to your retry policy, then use GET /agent-tools/api/jobs/{idempotency_key}. Use the original submission key; do not substitute a newly generated identifier. If the lookup finds an existing job, follow that job instead of creating a replacement. If submission must be replayed, retain the original key and unchanged payload. The documentation says reuse of the same key does not create another job or charge twice. Treat this as documented behavior, not an independently audited guarantee. The cited material does not specify idempotency retention. Before replaying an old, unresolved submission after a prolonged interruption, check the current documentation or ask support rather than assuming duplicate protection lasts indefinitely.
- Existing unfinished job: continue tracking it rather than submitting a new run.
- Existing successful job: retrieve and review its result rather than processing the input again.
- Existing failed job: reconcile its reservation before deciding whether a separate run is appropriate.
- Lookup unavailable or inconclusive: keep the outcome unresolved. Missing confirmation is not proof that no job exists.
- Do not assume replaying a terminally failed job with the same key restarts processing; that behavior is not established.
4. Bound recovery instead of multiplying retries
A retry mechanism needs both duplicate protection and traffic control. [AWS’s guidance on retries](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/) explains why failures can leave side effects uncertain and why retries at several layers can multiply load. Assign recovery to one coordinating layer rather than letting the HTTP client, queue worker and agent each retry independently. Honor a valid Retry-After header when present. [HTTP permits](https://www.rfc-editor.org/rfc/rfc9110.html#section-10.2.3) either an HTTP date or a nonnegative delay in seconds. Do not assume Agent Tools always sends this header. If the requested wait exceeds your integration’s deadline, defer or escalate rather than retry early.
- Use capped exponential backoff with jitter instead of immediate repeated requests.
- Set both an attempt limit and an overall recovery deadline.
- When the deadline expires, preserve the original key and report the last verified job state. If acceptance or completion remains unconfirmed, explicitly mark that outcome as unresolved.
- Do not treat a bare POST as safe to retry: preserve the documented application-level idempotency mechanism.
5. Reconcile job status with the credit ledger
[Skavio Agent Tools](https://getskavio.com/agent-tools/) uses a shared prepaid wallet and exposes reservations, consumption and refunds in its dashboard ledger. Submission reserves credits; successful jobs settle once, while permanent failure releases the reservation. A 503 response is not itself evidence that either settlement or release occurred. The material reviewed for this guide does not establish reservation-release timing. Close the incident only after the job record and credit records agree. If they do not, retain the discrepancy for support rather than promising that the request was free. Customer-credit outcomes are separate from any upstream provider costs. Before deploying the recovery path, exercise it with controlled tests. The following are proposed checks—not measured Skavio results:
- Simulate an initial 503 and verify that recovery preserves the original key and payload.
- Simulate a lost acceptance response and check that recovery follows the existing job instead of creating a replacement.
- Test an accepted job that ultimately fails, then reconcile its final state with the reservation release.
- For unresolved discrepancies, contact support@getskavio.com with the relevant job key, timestamps and sanitized error details—not API secrets or private source documents.