Handle errors

AudioLasso errors are designed to be simple to handle in code and readable by humans.

{
  "error": {
    "code": "INVALID_AUDIO_URL",
    "message": "input.audio_url must be a public HTTPS URL.",
    "param": "input.audio_url",
    "request_id": "req_01jabc"
  }
}

HTTP status codes

Queue logs

Use ?logs=true on status or stream endpoints to include short progress messages.

curl "https://audiolasso.dev/v1/queue/requests/req_01jabc/status?logs=true" \
  -H "Authorization: Bearer $AUDIOLASSO_API_KEY"

Logs are meant for humans and agents. Treat status as the source of truth for program logic.

Every /v1 response includes X-Request-Id for HTTP tracing. This is different from the durable queue request_id; record both when reporting an integration failure.

IDEMPOTENCY_CONFLICT means an Idempotency-Key was reused with a different request body. Generate a new key for new work; do not retry the conflicting body with the old key.

BILLING_UNAVAILABLE is different from INSUFFICIENT_CREDITS. Retry the former with the same idempotency key and backoff. The latter requires more credits or a smaller input.

RATE_LIMITED responses include Retry-After in seconds. The default API-key bucket allows 120 requests per minute; audio submissions use a separate 10-per-minute bucket. Limits are enforced atomically across application instances.

{
  "logs": [
    {
      "timestamp": "2026-04-25T08:00:00.000Z",
      "message": "Started audio separation"
    }
  ]
}

Recommended client behavior

• Branch on HTTP status and error.code.
• Show error.message to developers.
• Retry 408, 429, 500, 502, 503, 504, and network errors with backoff only when the request is read-only or idempotent.
• Do not retry 400, 401, 402, or 403 without changing the request or key.