Skip to main content
Work through this list before you go live. The reference 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.

​
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.
  • 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 and 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.

​
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.

​
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.
  • 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.