> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundpiece.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Production checklist

> What every integration should do before it goes live, and why

Work through this list before you go live. The [reference client](/client) already does the items marked *(client)*; if you write your own client, it needs to do them too.

## Keys

* **Load your API key from the environment or a secrets manager, never from code.** *(client)*
  Code gets committed, shared and shipped to browsers; anyone who finds the key can spend your credits. See [Authentication](/authentication).

## Submitting work

* **Use one idempotency key per job. Store it before the first attempt, and reuse it on every retry and every re-run.**
  The same key returns the original operation instead of starting the work again, so neither a dropped connection nor a restart of your program creates duplicate work or a duplicate charge. The client reuses its key across retries; to survive a restart, [pass it a key you stored](/client#keeping-an-idempotency-key-across-re-runs).
* **Put a timeout on every request.** *(client)*
  Without one, a stalled connection hangs your program forever. Use more than 20 seconds, so a long poll can finish.
* **Retry network errors, `429` and `5xx`, waiting as long as `Retry-After` says (or backing off exponentially when it's absent). Never retry any other `4xx` unchanged.** *(client)*
  The first group is temporary and safe to repeat with the same idempotency key; any other `4xx` means the request itself is wrong, so sending it again fails again. A `403` means your account doesn't currently have API access; retrying won't change that, so contact support. See [Rate limits](/rate-limits) and [Errors](/errors).
* **Handle `402 Payment Required`.**
  It means your account doesn't have enough credits for the request. Nothing was started or charged, so top up and send the same request again with the same idempotency key. See [Errors](/errors#insufficient-credits-402).

## Waiting for results

* **Poll with `wait=true`, and give up after a deadline; or use webhooks.** *(client: polling)*
  A long poll returns the moment the work finishes, without hammering the API, and a deadline stops one stuck job from blocking your program forever. Webhooks remove the waiting altogether. See [Async operations](/async-operations).

## Webhooks

* **Verify the signature of every delivery.**
  Your webhook URL is public; the signature is what proves a delivery came from Soundpiece and wasn't changed on the way. See [Signature verification](/webhooks#signature-verification).
* **Return a `2xx` straight away, and do the work afterwards.**
  A delivery must be answered within 10 seconds, or it counts as failed and is sent again. Downloading audio inside the handler can easily take longer.
* **Deduplicate on the `webhook-id` header.**
  A delivery can arrive more than once (for example after a timeout), and every attempt carries the same `webhook-id`.
* **Fall back to polling.**
  Polling is the source of truth. If a webhook hasn't arrived when you expected it, poll the operation.

## Results

* **Download the audio promptly, and never store the download URL.**
  Download URLs are signed and expire (see `expires_at`). When you need a fresh one, poll the operation again. Keep the audio you downloaded, not the link.
* **Branch on `error.code`, never on `error.message`.**
  Codes are stable identifiers; messages are written for people and can be reworded at any time. See [Errors](/errors#operation-level-failures).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.