Skavio Processing API: retry a timed-out submission without requesting another job
Skavio Processing API supports idempotent job submissions. Its documentation describes how identical requests sent with the same idempotency key return the same job without another charge. That matters when your client times out before receiving a response. The recovery pattern is to preserve one key and one request payload, retry that submission, then track the returned job ID—not generate a fresh request identity each time the network fails.
A timeout means the outcome is unknown
Consider an invoice-processing integration that submits a job, then loses its connection before the response arrives. The server may have accepted the request already. From the client’s perspective, however, there is no job ID to track. Treating that timeout as proof of failure creates the wrong recovery path: submit again as a new operation. Instead, treat the submission as unresolved and recover its outcome using the original request identity. This is the distinction behind idempotent APIs. RFC 9110 defines idempotency in terms of equivalent intended server effects, not identical response bytes. POST is not inherently idempotent; retry safety depends on the operation’s documented semantics. For Skavio, the documented mechanism is the Idempotency-Key header supplied to POST /v1/jobs.
Persist the key and payload before the first attempt
Create one identifier for the logical operation and store it durably alongside the exact submission payload before making the network request. A local variable is not enough if the process can restart between submission and response handling. Skavio’s documentation, checked for the research brief on October 14, 2026, specifies keys of 8–128 characters using letters, numbers, underscore, dot, colon or dash. Keep the stored payload unchanged when recovering a lost response, including its source references and processing parameters. Use the key to identify intent, not merely content. Two deliberate processing runs can use the same source file while representing different operations. A file hash alone therefore should not be your universal operation identifier.
- Store the logical operation reference, idempotency key and exact request payload before submission.
- Record the returned job ID durably as soon as it is available.
- After a client restart, load the existing operation record rather than generating another key.
Replay the submission within a bounded retry policy
After an ambiguous client or network timeout, retry POST /v1/jobs with the saved key and unchanged request. The documented behavior is that identical requests with the same key return the same job without another charge. Changed parameters with that key return HTTP 409. A conflict is a reason to inspect the operation record, not to bypass the check by automatically creating a new key. Establish whether the application is recovering the original submission or intentionally requesting different work. As an application-design recommendation, use capped exponential backoff with jitter and a maximum attempt count or elapsed-time budget. Choose one deliberate retry layer, accounting for any retries already performed by your HTTP client. Retry transport failures selectively; do not retry every error indiscriminately. For long-delayed recovery, first confirm the API’s idempotency-record lifetime rather than assuming replay protection lasts indefinitely.
- First attempt: send the persisted key and payload.
- Response lost: retry the same submission after a bounded delay.
- Job ID returned: save it and move to job tracking.
- Retry budget exhausted: preserve the unresolved submission for later reconciliation. Do not silently create a replacement operation.
Once you have a job ID, stop submitting
The documented acceptance response is HTTP 202 with a job ID. Acceptance is not completion: use GET /v1/jobs/{job_id} to follow the existing job. A timeout while checking status is not a reason to submit the processing request again. Transport recovery and processing recovery are different decisions. Recovering a lost submission response uses the original key and payload. Intentionally rerunning a terminally failed processing job requires a new job and a new key. For job accounting, submission reserves the measured quote, successful processing charges once, and permanent failure releases the reservation. Web tools and the API share one Pricing V2 wallet. These are job-accounting rules—not an end-to-end exactly-once guarantee for the rest of your integration.
Test the lost-response path—and keep the boundary clear
Test recovery before relying on it in production. In a controlled test environment, simulate a lost submission response and a client restart before the job ID is saved. Verify that your application reloads the original operation record, reuses its key and payload, and retains unresolved state when its retry budget expires. These are recommended tests, not results demonstrated for this article. Submission idempotency does not establish exactly-once behavior for uploads, webhook delivery, external providers or downstream ERP actions. Those steps need their own recovery and deduplication design. The available evidence does not establish Skavio’s idempotency-record lifetime, exact key namespace, concurrent replay behavior or behavior after deletion. Confirm those details before relying on them in your integration. In particular, the seven-day result-retention limit is not evidence of a seven-day idempotency window.