Errors - soundpiece API documentation

Why two layers of errors?

Soundpiece returns two distinct kinds of error, and they mean different things:

HTTP-level errors (4xx / 5xx) — your request was rejected. The work never started.
Operation-level errors — your request was accepted (you got 200 OK and an operation id), but the operation itself failed during processing. You poll the operation just like any other and find status: "failed" with a populated error object.

This split is deliberate: the request layer is about whether you talked to us correctly, the operation layer is about whether the work succeeded. They have different causes, different retry rules, and different recovery strategies. A successful HTTP response doesn’t mean the operation succeeded — you still need to check status.

HTTP errors

The two rules of thumb:

4xx — fix your request. Something in what you sent doesn’t work. Retrying with the same body won’t help; you need to change the request.
5xx — something unexpected happened on our side. You can retry. PUT endpoints are idempotent on idempotency_key (see Async operations), so retrying with the same key is safe — you won’t double-create work.

Response shape

HTTP errors return a JSON body with a detail field. For most errors it’s a plain string:

{
  "detail": "Missing or invalid Authorization header"
}

For request-body validation errors (422), detail is a list of per-field entries:

{
  "detail": [
    {
      "loc": ["body", "lyrics"],
      "msg": "String should have at least 1 character",
      "type": "string_too_short"
    },
    {
      "loc": ["body", "idempotency_key"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Field	Meaning
`loc`	Path to the offending field — e.g. `["body", "lyrics"]` for a top-level body field, or `["body", "reference", "url"]` for a nested one.
`msg`	Human-readable description of the problem.
`type`	Stable machine-readable code (e.g. `missing`, `string_too_short`, `url_parsing`).

Status reference

Status	When you’ll see it	Recommended handling
`400 Bad Request`	Malformed JSON or unparseable request body.	Fix the request.
`401 Unauthorized`	Missing, invalid, or revoked API key (and, on Enterprise plans with IP allowlisting, a request from a non-allowlisted IP).	Check your `Authorization` header and source IP. Don’t retry.
`402 Payment Required`	Your account doesn’t have enough credits to perform the requested work. See Insufficient credits below for the response shape.	Top up your account, then retry with the same `idempotency_key`.
`404 Not Found`	Only returned when the endpoint URL itself doesn’t exist — e.g. a typo in the path. Entity-not-found (operation id, etc.) is reported as a `422` validation error, not a `404`.	Check the URL.
`405 Method Not Allowed`	Wrong HTTP verb on a known route (e.g. `POST` on a `PUT`-only endpoint).	Use the documented verb.
`410 Gone`	The endpoint existed on this API version but has been sunset. The `detail` field points to the replacement.	Migrate to the replacement endpoint. See versioning.
`422 Unprocessable Entity`	Request body validation failed — missing field, wrong type, out-of-range value, invalid URL, or a referenced entity (operation `id` etc.) wasn’t found.	Read `detail` to see which field is bad.
`429 Too Many Requests`	You’ve hit your account’s request rate limit.	Read the `Retry-After` header (seconds) and back off. See rate limits.
`5xx`	Transient server-side issue.	Retry safely — `PUT` requests are idempotent if you supply the same `idempotency_key`. Use exponential backoff.

Insufficient credits (`402`)

When you submit a request whose credit cost exceeds your current balance, the call is rejected up-front (no work starts, no charge) with a 402 whose body is:

{
  "detail": {
    "type": "insufficient_credits",
    "msg": "You have insufficient credits to perform this action."
  }
}

The per-endpoint credit cost is documented on each endpoint (e.g. create.remix_song and create.remix_instrumental charge 3 credits per variation, so n_variations: 3 costs 9). Top up your account and re-submit with the same idempotency_key — the original request was never persisted, so the retry creates the work fresh.

Operation-level failures

When an operation fails, the response looks like this:

{
  "song": {
    "id": "op_01h7k...",
    "status": "failed",
    "error": {
      "code": "tos_violation",
      "message": "The provided lyrics were rejected by our content policy."
    },
    ...
  }
}

error.code is a stable machine-readable identifier — safe to branch on. error.message is a human-readable description suitable for surfacing to your end-users. Not every code applies to every endpoint. The sections below group codes by which endpoints can return them.

Codes returned by all endpoints

Code	Meaning	Recommended handling
`internal_error`	Generic failure with no more specific classification available.	Re-submit with the same `idempotency_key`. If it persists, contact support.
`generation_timeout`	The operation took longer than our hard timeout to complete.	Re-submit. Persistent timeouts are worth raising with support.
`quota_exceeded`	Your account is out of monthly capacity.	Top up your account or wait for the next billing cycle.

Codes for endpoints with a `source` or `reference`

(applies to adapt.separate_stems, adapt.auto_cut_down, create.remix_song, create.remix_instrumental, and the reference variant of create.new_song / create.new_instrumental)

Code	Meaning
`source_unreachable`	We couldn’t fetch the URL — DNS failure, connection refused, TLS error, 4xx/5xx from the host.
`source_format_unsupported`	The file at the URL is not a supported audio format (we accept wav, mp3, flac).
`source_too_short`	The fetched audio is too short for this operation (typically under 10 seconds).
`source_too_long`	The fetched audio exceeds the maximum length for this operation.

Codes for generation endpoints

(applies to create.new_song, create.new_instrumental, create.new_sample, create.new_fx, create.remix_song, create.remix_instrumental)

Code	Meaning
`tos_violation`	The lyrics, prompt, or reference were rejected by our content policy.

Why retries don’t risk double-billing

PUT endpoints are idempotent on idempotency_key. The same key always returns the same operation, regardless of how many times you retry. This means:

5xx HTTP responses are safely retryable — retry with the same key and you’ll either get a fresh attempt or the existing successful result.
429 is retryable — back off using Retry-After, then send the same key again.
4xx other than 429 indicate a bad request that won’t get better; fix the request before retrying.

You will never accidentally create two operations from one logical request, no matter how many times the network drops between you and us. The idempotency_key is also echoed on every response and webhook payload so you can correlate work against your own records without a separate request-id-to-state map.

Reporting persistent issues

If you receive internal_error (operation-level) or 5xx (HTTP-level) that persists across retries, please contact business@soundpiece.co.uk with:

The endpoint called.
The operation id if one was returned.
The idempotency_key you sent.
The approximate timestamp.
Any error.code / error.message from the response body.

​Why two layers of errors?

​HTTP errors

​Response shape

​Status reference

​Insufficient credits (402)

​Operation-level failures

​Codes returned by all endpoints

​Codes for endpoints with a source or reference

​Codes for generation endpoints

​Why retries don’t risk double-billing

​Reporting persistent issues