Design a Reliable Audio-Cleanup API Workflow

Create a job ledger before sending files

Assign each source a stable internal task reference. Record its permitted processing purpose, file properties, intended mode, output requirement and current state. Keep content and personal filenames out of general logs. Store an accepted provider job reference against that task so a restarted worker can resume status checks.

Suggested internal states are prepared, submitting, accepted, waiting, completed, saved and failed. They are your application states, not a claim about the provider’s exact status strings.

Limit submissions and spending

Validate extension, size and duration before transfer, while still handling server-side rejection. Check effective plan, available usage and the route’s transport ceiling. The website API direct-upload route is separate from Studio chunks; do not assume the same maximum size.

Use bounded concurrency, a usage budget and a stop condition. Review the current API prices and allowances before enabling recurring work. A configured queue priority is not a delivery-time SLA.

Treat ambiguous submissions differently from polling

Retrying a status request and retrying an upload are not equivalent. If a submit times out after reaching the server, repeating it may create another job and use more minutes. Do not assume idempotency support without checking the contract. Preserve the task for investigation when acceptance is uncertain.

For retryable status failures, use backoff, respect rate-limit instructions and impose a deadline. Surface exhausted retries to an operator rather than silently abandoning the task.

Do not confuse a callback with verified output

Where your plan and the current API support callbacks, confirm the documented authentication and payload before trusting them. Do not assume the mobile RevenueCat HMAC format applies to audio-job callbacks. Deduplicate notifications in your own ledger and verify the authorised job state before taking consequential action.

Keep callback URLs private where appropriate and avoid logging credentials or temporary download URLs.

Persist and review the result

Save completed output before its displayed expiry, validate it and update the ledger only after storage succeeds. A completed provider job can still have a failed download in your application. For video, inspect duration and sync; for speech, keep a review path for artifacts or missing words.

• Alert on repeated failures or stalled tasks.
• Keep originals under your own disclosed retention policy.
• Reconcile usage against accepted jobs.
• Test failure cases with non-sensitive fixtures before rollout.

The API starting guide explains the website endpoints. No new live processing was run to create this local draft.