A Failed Agent Tools Job Is a Reconciliation Problem, Not a Retry Button
Failed asynchronous jobs are rarely tidy. A client can time out while the server-side job remains unresolved, and a credit reservation can exist separately from any payment record. In Skavio Agent Tools, the safe sequence is deliberate: establish what the server recorded, reconcile the credit entry on its own terms, and only then decide whether a retry is justified. Treating those steps as one—or pressing submit again—can turn a recoverable ambiguity into duplicate work and a confusing ledger.
Establish the server-side state before calling the job failed
Start with the job record, not the last screen your client displayed. Skavio Agent Tools is a company-scoped authenticated processing API for documents, invoices, audio and data, with a shared prepaid credit wallet, self-service keys and asynchronous jobs. Because the work is asynchronous, the absence of an immediate result says nothing about failure. A dropped connection or client timeout is an unknown state. The documented job state or a signed completion event should determine the outcome; verify a webhook before it changes local records. Skavio's processing API documentation describes controls that help here—fixed quotes, atomic credit reservations and idempotent job submissions—but they do not remove the need to check the server. Confirm the current Agent Tools status fields and failure wording in its documentation.
- Record the idempotency key, request timestamp, any returned job ID and the server quote reference.
- Treat a timeout or dropped connection as unknown, not permanent; poll the documented status or wait for a signed completion event.
- Verify the completion webhook signature before marking a job complete or failed in your system.
- Do not submit a fresh job merely because your client never displayed the first result.
Reconcile credits as a separate ledger
Credit reconciliation is not payment reconciliation. The shared wallet covers web tools and API processing. Skavio's processing documentation describes the server quote at submission as authoritative, a successful job as settling once, and a permanent failure as releasing the credit reservation. Those are processing-credit events. They remain distinct from provider costs, cash receipts and company revenue. A held reservation is not evidence of successful processing, and a released reservation is not a cash refund or a reversal of a separate payment record. Confirm the exact Agent Tools failure wording and reservation behavior in the current documentation before encoding assertions about timing or status labels.
- Record the quote reference and reservation outcome separately from the job state.
- Record a credit as settled only when the server records successful processing.
- Record a reservation as released only after the documented permanent-failure condition is confirmed.
- Keep credits, provider costs, cash receipts and revenue in separate columns rather than one blended balance.
Make every retry distinguishable from the original attempt
A retry is justified only after the original job has a terminal server state and the reservation outcome is understood. If the first request is still unknown, resolve that state before creating another job. If the job failed permanently, inspect the documented failure reason: some failures may require a corrected file, permission change or different input rather than blind repetition. When a new processing attempt is justified, obtain a fresh server quote and keep the new attempt visibly linked to the failed one. Use the documented idempotency mechanism so the new submission is distinguishable, and preserve the original job ID, quote reference and failure code so later review does not confuse two attempts as one job.
- Retry only after a terminal state and a confirmed reservation outcome.
- Resolve unknown submissions before requesting a new quote.
- For a justified retry, use a fresh quote and a distinguishable request identifier.
- Link the retry to the original job and record why the original attempt did not complete.
Keep an exception trail that survives a shift change
The useful output of reconciliation is not a cleaned-up story; it is an auditable record. Preserve the job state transitions, webhook delivery identifier, reservation outcome and authenticated download reference. Company isolation matters here: retrieve results through authenticated result downloads for the requesting company, not through ad hoc links. Before building automation around these fields, confirm current endpoint names, authentication methods, failure codes and response schemas in the official Agent Tools documentation and the published OpenAPI contract. Then review unresolved jobs and released reservations as exceptions at a cadence your team sets, rather than treating them as completed work.
- Maintain fields for request ID, idempotency key, quote reference, job ID, state history, webhook delivery ID, reservation outcome and result reference.
- Review unresolved jobs, permanent failures and released reservations as separate exception queues.
- Use authenticated downloads and company-scoped access when retrieving results.
- Confirm schemas and failure codes in the official documentation before writing production code.