Reliability and retries

AudioLasso jobs are asynchronous. A client can disconnect after the server accepts a request, so production integrations must distinguish “I did not receive the response” from “the job was not created.”

Make every submission idempotent

Send a stable Idempotency-Key with POST /v1/queue/audio/separate:

curl -X POST https://audiolasso.dev/v1/queue/audio/separate \
  -H "Authorization: Bearer $AUDIOLASSO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: workflow-job-123" \
  -d '{
    "input": {
      "audio_url": "https://example.com/audio.wav",
      "prompt": "isolate the lead vocal"
    }
  }'

The key is scoped to the API key. Repeating the same key and body returns the original request_id and sets Idempotent-Replayed: true. Reusing the key with a different body returns 409 IDEMPOTENCY_CONFLICT.

The TypeScript SDK creates a unique idempotency key automatically. Supply your own when a workflow may restart in another process:

const job = await client.separate({
  audioUrl: "https://example.com/audio.wav",
  prompt: "isolate the lead vocal",
  idempotencyKey: `customer-order-${orderId}`,
});

Configure client retries and timeouts

The SDK retries idempotent submissions and read requests on 408, 429, 500, 502, 503, and 504. It honors Retry-After and uses exponential backoff with jitter.

Rate limits are scoped to an API key. General API traffic allows 120 requests per minute, while new audio submissions use a separate 10-per-minute bucket. A 429 RATE_LIMITED response includes Retry-After; do not switch idempotency keys when retrying the same submission.

const client = createAudioLasso({
  requestTimeoutMs: 30_000,
  maxRetries: 2,
});

Retries do not extend waitForResult forever. Bound the whole wait separately:

const result = await client.waitForResult(job.request_id, {
  timeoutMs: 10 * 60_000,
  interval: 3,
});

If a wait times out, keep the request_id. The job continues and can be resumed from another process.

Choose one durable completion path

• Poll status_url for the smallest and most portable integration.
• Use stream_url for a live CLI or browser session; reconnect or fall back to polling when the stream window closes.
• Use a webhook for a backend callback. Queue status and result endpoints remain the source of truth.

AudioLasso reconciles queued work independently of client polling. A caller does not need to remain connected for processing, output persistence, billing finalization, or webhook retries.

Input retrieval happens inside the spawned worker, so submission does not wait for a large media download. Completed media is uploaded directly from Modal to short-lived signed R2 upload URLs; queue status carries only metadata instead of embedding large base64 outputs in a serverless response.

For local-file uploads, AudioLasso verifies that the R2 object exists and its byte length exactly matches the declared file_size before changing the file to uploaded or allowing submission. An incomplete PUT remains pending; a mismatched object returns FILE_SIZE_MISMATCH.

Jobs have a 30-minute processing deadline. A job that cannot reach a terminal model state by then is marked failed, its credit reservation is released, and it can be submitted again with a new idempotency key.

Cancel work that is no longer needed with POST /v1/queue/requests/{request_id}/cancel, client.cancel(requestId), the CLI cancel command, or the MCP cancellation tool. Cancellation propagates to Modal and releases the reservation.

Understand credit reservation and settlement

AudioLasso reserves the estimated whole-second usage atomically when it creates a job. Reservations prevent concurrent agent runs from spending the same balance. A successful job is settled against Autumn once, using the queue request as the billing idempotency key; a failed job releases its reservation.

The result and completion webhook expose the settlement state in usage.billing_status:

• deducted: billing was settled successfully.
• pending: output is ready, but billing settlement is being retried by the reconciler.
• not_metered: no metered usage applies.

Never infer billing state only from status: COMPLETED; read usage.billing_status when reconciling usage.

Treat webhooks as at-least-once delivery

Webhook handlers should:

1. Read the raw request body.
2. Verify AudioLasso-Signature against {timestamp}.{raw_body}.
3. Reject stale AudioLasso-Timestamp values.
4. Deduplicate on request_id.
5. Persist the event before returning a 2xx response.

AudioLasso makes up to three delivery attempts. A webhook failure never changes the job result; recover by polling the same request_id.

Debug with request IDs

Every /v1 response includes X-Request-Id. Log it with the AudioLasso request_id: the first traces one HTTP request, while the second identifies the durable queue job.