Skavio Processing API: quote-first jobs, idempotent retries, one wallet
Skavio Processing API shares one company credit wallet with Skavio’s web processing tools and supports fixed quotes, atomic credit reservations and idempotent job submissions. To use those controls well, separate two decisions: whether to authorize processing, and whether to retry delivery of an already authorized request. A lost HTTP response should not automatically become a second processing job.
1. Use the estimate to approve work—not to reserve credits
Build the integration around a deliberate sequence: upload the source, select the operation and configuration, obtain a server estimate, then approve a credit ceiling before submission. The estimate gives your application a basis for deciding whether the work is acceptable; it does not start processing or reserve credits. The submission-time server quote is authoritative. Do not assume an earlier estimate locks the price indefinitely or guarantees that sufficient credits will remain available. Confirm the current estimate and submission schemas in the API documentation before implementation, including how any server-enforced credit ceiling works. A ceiling stored only in your application is not, by itself, a server-side limit.
- Associate the estimate and approval with the exact source files, operation and processing settings.
- If the source or configuration changes, reassess the estimate and approval rather than silently reusing them.
- Keep approval separate from submission so a network retry does not ask the business to authorize the same work again.
2. Keep quote, reservation and settlement distinct
These are separate stages of the credit lifecycle. The quote establishes the job’s credit amount. An atomic reservation sets aside credits for the accepted work. A successful job settles once; a permanent failure releases its reservation. The shared wallet makes this distinction operationally important. A colleague using Skavio Flow in the browser and an integration submitting API jobs draw from the same company balance. An earlier balance check is therefore a planning signal, not a substitute for the server’s reservation.
- Quote: record the server’s job price separately from an earlier estimate.
- Reservation: track credits reserved for unfinished work separately from settled consumption.
- Settlement or release: reconcile the terminal outcome. Releasing a credit reservation is not a cash refund.
3. Persist the request’s identity before sending it
Before the first submission attempt, save a durable record of the intended work. At minimum, keep your business-request identifier, company context, source references, operation and settings, approved credit ceiling, and stable idempotency key. Add the server job identifier when it becomes available. These are recommended integration records, not a proposed API payload schema. Skavio supports idempotent submissions, but implementation details matter. Confirm the current contract for key placement, replay behavior, payload conflicts, deduplication scope and key lifetime. Do not assume deduplication lasts indefinitely. The key should represent one authorized processing request—not every attempt to transmit it. A source-file hash alone does not capture that distinction: the same file may legitimately be processed twice for different purposes. Conversely, changing the key after a timeout can turn an accidental repeat into a new submission.
4. Recover a lost response without creating a new request
Consider an illustrative invoice-extraction request. Your server submits the approved payload, but the connection times out before it receives a response. The job might have been accepted; the timeout does not establish failure. Load the persisted request record. If you already have a job identifier, check that job’s status. If the submission outcome remains uncertain, replay only under the API’s documented idempotency conditions, using the original key and unchanged payload. Check that the request remains within the documented replay scope and key lifetime. If safe replay cannot be established, pause automatic resubmission and reconcile the outcome rather than generating a fresh key. HTTP does not make an arbitrary POST safely retryable. RFC 9110 advises against automatically retrying a non-idempotent request unless the client knows the operation is effectively idempotent or knows the original request was never applied. The application-level contract matters. An intentional new job after confirmed terminal failure is a separate processing decision, not transport recovery.
- Use bounded retries with capped exponential backoff and jitter for eligible transient failures.
- Avoid independent retry loops at several layers; they can multiply traffic during an outage.
- For HTTP 429 rate-limit responses, respect Retry-After when supplied. This does not imply Skavio always sends that header.
- Do not blindly retry validation or authorization errors.
5. Reconcile completion before handing results downstream
Once the job identifier is known, monitor that job rather than submitting another. Skavio supports signed completion webhooks and authenticated result downloads. Validate webhook signatures according to the current contract, then retrieve results through authenticated access and save them to your own controlled storage when needed. Submission idempotency does not make the whole business workflow exactly once. Importing an extraction result into accounting software, for example, needs its own duplicate protection. Tie that handoff to a durable request or job reference and record whether it has already succeeded. Before production, test the failure paths as deliberately as the successful one. The following are recommended integration tests, not reported test results:
- Lose a submission response and verify recovery using the original request identity.
- Test unchanged replay and changed-payload reuse against the documented idempotency contract.
- Submit competing jobs against the shared balance and reconcile their reservation outcomes.
- Verify reservation release after permanent failure and prevent duplicate downstream imports.