Errors

Format

Errors return application/problem+json (RFC 9457):

{
  "type": "https://disband.io/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "instance": "/v1/separations",
  "request_id": "8a1f2c3d4e5f6a7b",
  "errors": [
    {
      "path": "stems.1",
      "message": "not a stem in the catalog"
    }
  ]
}

• type identifies the problem and links to its section on this page. Use it in code, not title.
• detail, when present, describes this occurrence.
• errors lists each invalid parameter or field with its path, for invalid-request only.
• request_id identifies the request. Include it when contacting support.

Retrying

Retry busy (429) and capacity (503) after the seconds in Retry-After. Other errors repeat until the request or the account changes.

Failed separations

Some problems occur after a separation has started. The separation then has status: "failed" and the problem in problem, with instance set to the separation's URL: bad-audio, capacity, timeout and internal, and for a reserved upload also out-of-credits, upload-timeout, account-locked and account-suspended. Failed separations are not retried automatically.

Problem types

invalid-request

400 Invalid request

A query parameter or body field is missing or invalid, or a stem isn't in the catalog. errors lists each one.

upload-timeout

408 Upload took too long

A reserved upload didn't arrive within its window. Nothing is charged.

unauthenticated

401 Not authenticated

The key is missing, malformed, unknown or revoked. See Authentication.

out-of-credits

402 Out of credits

The balance doesn't cover the separation's price. Requests with an API key use bought credits only. See Credits.

account-suspended

403 Account suspended

The account is suspended and can only read /usage. Contact support for the reason.

not-found

404 Not found

The separation, stem or key doesn't exist, has expired, or belongs to another account. Downloads of silent stems also return this.

account-locked

409 Account being deleted

The account is being deleted and can't start separations.

length-required

411 Length required

The request has no Content-Length. Send the file as a plain body of known length, not chunked.

unsupported-audio

415 Unsupported audio format

The file's format isn't supported. Supported formats: WAV, FLAC, MP3, AAC, ALAC, Ogg Vorbis and Opus.

range-not-satisfiable

416 Range not satisfiable

The Range header starts past the end of the file.

bad-audio

422 Unusable audio

The file can't be used: it has no audio, can't be decoded, has more than two channels, is longer than the account's limit (see Limits), or a reserved upload's size differs from bytes. Nothing is charged when the create returns this. When the GPU finds it, the separation keeps the minimum of 10 credits.

busy

429 Too many jobs running

The account runs as many separations as it may at once. Retry after Retry-After seconds.

internal

500 Internal error

An error on our side, reported to us automatically. All credits are refunded. Quote the request_id to support if it repeats.

capacity

503 No capacity

No GPU could take the separation. Retry after Retry-After seconds. All credits are refunded.

timeout

504 Separation timed out

The separation exceeded its time limit. All credits are refunded.

Web app only

These occur in the web app's sign-in, account and billing pages, not with an API key.

sign-in-failed

400 Sign-in failed

The sign-in provider refused the sign-in, or it was cancelled.

provider-unavailable

503 Sign-in unavailable

The sign-in provider couldn't be reached.

cross-site

403 Cross-site request refused

A request with the session cookie came from another site.

identity-linked

409 Identity linked to another account

The sign-in identity belongs to another account.

provider-linked

409 Provider already linked

The account already has an identity from this provider.

last-provider

409 Last sign-in provider

The account's last sign-in method can't be removed.

limit-reached

409 Limit reached

The account has the maximum number of keys. Revoke one to create another.

payment-unavailable

503 Payments unavailable

Payments can't be processed at the moment.

refund-failed

502 Refund failed

The payment provider rejected the refund.

conflict

409 Changed meanwhile

The account changed during a refund or deletion. Try again.