Errors

Every error response is an RFC 9457 problem document with the fields below. The type is a stable URL you can match on; title and detail are for people and can change.

{
  "type": "https://esfera.audio/errors/quota-exhausted",
  "title": "Quota exhausted",
  "status": 403,
  "detail": "No conversion minutes left for this job."
}

Field	Meaning
type	One of the URLs below, https://esfera.audio/errors/<slug>. Stable.
title	A short label. Do not match on it.
status	The HTTP status, repeated.
detail	What went wrong in this case.

A response can also carry cf-ray, the edge request id. Quote it, with the conversion id, when you contact support.

Retry only what can change: 429, 5xx and network errors. A 4xx other than 429 will fail the same way again until you change the request.

400 Bad request

invalid-request

https://esfera.audio/errors/invalid-request

A required field is missing or malformed. Fix the request body.

Returned by: POST /v1/conversions, POST /v1/webhooks.

401 Unauthorized

invalid-api-key

https://esfera.audio/errors/invalid-api-key

The key is missing, malformed, unknown, revoked, expired, or for the other environment. Check the Authorization header and which host you are calling.

Returned by: any operation except GET /v1/openapi.json.

403 Forbidden

quota-exhausted

https://esfera.audio/errors/quota-exhausted

The account has no conversion minutes left for this job. Top up or wait for the monthly reset.

Returned by: POST /v1/conversions, POST /v1/conversions/{id}/start.

404 Not found

not-found

https://esfera.audio/errors/not-found

No such resource for this account. Ids are account-scoped.

Returned by: GET /v1/conversions/{id}, DELETE /v1/conversions/{id}, POST /v1/conversions/{id}/multipart/init, POST /v1/conversions/{id}/multipart/complete, POST /v1/conversions/{id}/multipart/abort, POST /v1/conversions/{id}/analyze, POST /v1/conversions/{id}/start, GET /v1/conversions/{id}/output, DELETE /v1/webhooks/{id}, GET /v1/webhooks/{id}/deliveries, POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay, GET /v1/openapi.json.

409 Conflict

concurrency-limit

https://esfera.audio/errors/concurrency-limit

Too many conversions in flight. Wait for one to finish, then retry.

Returned by: POST /v1/conversions.

already-started

https://esfera.audio/errors/already-started

The conversion is past the state this call applies to. Read its status first.

Returned by: POST /v1/conversions/{id}/multipart/init, POST /v1/conversions/{id}/multipart/complete, POST /v1/conversions/{id}/multipart/abort, POST /v1/conversions/{id}/analyze, POST /v1/conversions/{id}/start.

programme-required

https://esfera.audio/errors/programme-required

The file declares several programmes. Pass programme (0-based) on start.

Returned by: POST /v1/conversions/{id}/start.

source-removed

https://esfera.audio/errors/source-removed

The source was removed by retention. Upload it again.

Returned by: POST /v1/conversions/{id}/start.

webhook-limit

https://esfera.audio/errors/webhook-limit

The account is at its active-endpoint cap. Revoke one first.

Returned by: POST /v1/webhooks.

replay-in-flight

https://esfera.audio/errors/replay-in-flight

This delivery is already queued or retrying. Wait for it to settle.

Returned by: POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay.

422 Unprocessable

unknown-preset

https://esfera.audio/errors/unknown-preset

preset is not one of the ids GET /v1/presets lists.

Returned by: POST /v1/conversions.

invalid-programme

https://esfera.audio/errors/invalid-programme

programme must be a non-negative integer (0-based) within the file's programme count.

Returned by: POST /v1/conversions.

invalid-source-normalization

https://esfera.audio/errors/invalid-source-normalization

source.normalization must be sn3d, n3d or fuma; fuma is first order only; it applies to ambisonic sources only.

Returned by: POST /v1/conversions, POST /v1/conversions/{id}/start.

preset-not-for-source

https://esfera.audio/errors/preset-not-for-source

This preset cannot take this source yet (a first- or second-order ambisonic source into the 3OA scene presets). Use esfera or youtube, or a third-order source.

Returned by: POST /v1/conversions/{id}/start.

invalid-profile

https://esfera.audio/errors/invalid-profile

profile must be a profile id from GET /v1/presets, or "auto".

Returned by: POST /v1/conversions.

profile-not-writable

https://esfera.audio/errors/profile-not-writable

This encoder reads that profile but will not declare it. Pick a writable one.

Returned by: POST /v1/conversions.

preset-over-cap

https://esfera.audio/errors/preset-over-cap

This preset's plan exceeds its IAMF profile budget for this master; the analysis says why. Pick a preset the analysis marks as fitting.

Returned by: POST /v1/conversions/{id}/start.

file-too-long

https://esfera.audio/errors/file-too-long

The source exceeds the per-file duration cap. Split it.

Returned by: POST /v1/conversions.

file-too-large

https://esfera.audio/errors/file-too-large

The source exceeds the per-file size cap (bytes). Fewer channels or a shorter master.

Returned by: POST /v1/conversions.

invalid-multipart

https://esfera.audio/errors/invalid-multipart

parts must be an integer from 1 to 10000; uploadId and parts are required on complete.

Returned by: POST /v1/conversions/{id}/multipart/init, POST /v1/conversions/{id}/multipart/complete, POST /v1/conversions/{id}/multipart/abort.

invalid-webhook-url

https://esfera.audio/errors/invalid-webhook-url

The endpoint URL is not allowed (https only, no private hosts).

Returned by: POST /v1/webhooks.

429 Too many requests

rate-limited

https://esfera.audio/errors/rate-limited

Too many requests for this key. Honour Retry-After.

Returned by: any operation except GET /v1/openapi.json.

500 Server error

internal

https://esfera.audio/errors/internal

Something failed on our side. Retry; if it persists, contact support with the conversion id.

Returned by: POST /v1/conversions, GET /v1/conversions, DELETE /v1/conversions/{id}, POST /v1/conversions/{id}/multipart/init, POST /v1/webhooks, DELETE /v1/webhooks/{id}, GET /v1/webhooks/{id}/deliveries, POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay, GET /v1/usage.

502 Bad gateway

upload-failed

https://esfera.audio/errors/upload-failed

Storage refused to finalise the upload; retry the upload from the start.

Returned by: POST /v1/conversions/{id}/multipart/complete.

503 Service unavailable

queue-unavailable

https://esfera.audio/errors/queue-unavailable

The delivery queue is not configured on this environment.

Returned by: POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay.

queue-send-failed

https://esfera.audio/errors/queue-send-failed

The delivery queue did not accept the replay. Try again shortly.

Returned by: POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay.