Errors

HTTP 401 · invalid_api_key

Invalid or revoked API key

Cause. The Authorization header carries a key we do not know: it is misspelled, was revoked, or was cut off. On the analysis routes a request with no Authorization header at all is not this error: it runs as the keyless trial. /v1/batch and /v1/usage always need a key and answer with this error when there is none.

What to do. Send it exactly as "Authorization: Bearer al_live_..." (the whole key, no quotes). A key is shown once when you create it; if you lost it, make a new one on /account and revoke the old one.

{
  "error": {
    "type": "unauthorized",
    "message": "Invalid or revoked API key.",
    "code": "invalid_api_key",
    "docs_url": "https://audiolab.tools/docs/errors#invalid_api_key"
  }
}

HTTP 429 · rate_limited

Too many requests this minute

Cause. More requests in a minute than your key allows: 60 on the free tier, 120 on Plus, 300 on Studio. The keyless trial allows 3 a minute.

What to do. Wait the number of seconds in the Retry-After header (60) and send fewer requests at once. The "usage" field in the error says how many you sent in the window and what the limit is. For many files at once use /v1/batch.

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded: max 60 requests/minute. Retry shortly.",
    "code": "rate_limited",
    "docs_url": "https://audiolab.tools/docs/errors#rate_limited",
    "usage": {
      "window": "minute",
      "limit": 60,
      "used": 61
    }
  }
}

HTTP 402 · quota_exceeded

Monthly call limit reached

Cause. Your account has used its calls for this month: 1,000 on the free tier, 10,000 on Plus. Every accepted request counts, including one that failed later. The keyless trial has 20 calls a month. All keys of one account share one allowance.

What to do. The count starts again on the 1st of the month (UTC). To go on now, upgrade on /pricing, or email partners@audiolab.tools. The "usage" field in the error shows the limit and what has been used.

{
  "error": {
    "type": "quota_exceeded",
    "message": "You've hit your monthly call limit (1000 calls). You're flagged for a bump.",
    "code": "quota_exceeded",
    "docs_url": "https://audiolab.tools/docs/errors#quota_exceeded",
    "usage": {
      "window": "month",
      "limit": 1000,
      "used": 1001
    }
  }
}

HTTP 402 · data_quota_exceeded

Monthly data limit reached

Cause. Your account has processed its audio volume for this month: 2 GB on the free tier, 20 GB on Plus. The keyless trial has 200 MB.

What to do. The volume starts again on the 1st of the month (UTC). To go on now, upgrade on /pricing or email partners@audiolab.tools. Analysing a shorter section of each file also uses less.

{
  "error": {
    "type": "quota_exceeded",
    "message": "You've hit your monthly data limit (2 GB processed). You're flagged for a bump.",
    "code": "data_quota_exceeded",
    "docs_url": "https://audiolab.tools/docs/errors#data_quota_exceeded"
  }
}

HTTP 402 · profile_requires_paid_plan

This preset needs a paid plan

Cause. You asked /v1/analyze/profile for a preset that is not on the free tier. The free tier covers the "basic" preset.

What to do. Use profile "basic", or upgrade on /pricing. The error message names the presets your plan includes.

{
  "error": {
    "type": "quota_exceeded",
    "message": "The \"dataset\" preset is a paid-tier feature. Free covers basic: upgrade on https://audiolab.tools/pricing (the Founder lifetime counts).",
    "code": "profile_requires_paid_plan",
    "docs_url": "https://audiolab.tools/docs/errors#profile_requires_paid_plan"
  }
}

HTTP 413 · file_too_large

File too large

Cause. The audio is over the per-file limit of 150 MB, or you sent it as a raw request body, which the platform caps at about 4.5 MB.

What to do. Send a public URL in a JSON body instead of the file itself ({"url": "https://..."}), or upload it through the signed-upload route and send the objectPath it returns. Or analyse a section of the file.

{
  "error": {
    "type": "payload_too_large",
    "message": "file too large",
    "code": "file_too_large",
    "docs_url": "https://audiolab.tools/docs/errors#file_too_large"
  }
}

HTTP 413 · track_too_long

Recording too long

Cause. The recording decodes to more audio than a single request can hold. MixLab routes stream long files up to 3 hours; the voice and signal routes have a lower ceiling.

What to do. Cut the recording into sections and send them one by one (or in one /v1/batch call), or use a mixlab route for the full length.

{
  "error": {
    "type": "payload_too_large",
    "message": "This file decodes to 412 MB of PCM, above the 170 MB budget. Analyse a section instead.",
    "code": "track_too_long",
    "docs_url": "https://audiolab.tools/docs/errors#track_too_long"
  }
}

HTTP 422 · unsupported_format

This is not audio we can read

Cause. We fetched or received the bytes, but they did not decode as audio: an unsupported or damaged file, or a URL that points to a web page instead of the audio file.

What to do. Check that the URL opens the audio file itself (WAV, MP3, FLAC, OGG, M4A and AIFF work), that the file plays, and that a Content-Type header is not hiding an error page. Try the same file as WAV.

{
  "error": {
    "type": "unprocessable",
    "message": "Could not decode this as audio. Check that the source is an audio file in a supported format.",
    "code": "unsupported_format",
    "docs_url": "https://audiolab.tools/docs/errors#unsupported_format"
  }
}

HTTP 400 · url_not_allowed

URL not allowed

Cause. The URL points somewhere we refuse to fetch from: a private or internal address, an unsupported scheme (only http and https), or it redirected somewhere that is.

What to do. Use a public https URL. For a file on your own machine or network, upload it through the signed-upload route and send the objectPath.

{
  "error": {
    "type": "invalid_request",
    "message": "URL not allowed",
    "code": "url_not_allowed",
    "docs_url": "https://audiolab.tools/docs/errors#url_not_allowed"
  }
}

HTTP 400 · url_fetch_failed

Could not fetch the audio

Cause. We tried to download the URL and it did not work: it timed out (we wait 20 seconds), answered with an error, needs a login, or the host could not be found.

What to do. Open the URL in a private browser window to check it works without signing in. For a private file, create a temporary public link, or upload it through the signed-upload route.

{
  "error": {
    "type": "invalid_request",
    "message": "could not fetch audio",
    "code": "url_fetch_failed",
    "docs_url": "https://audiolab.tools/docs/errors#url_fetch_failed"
  }
}

HTTP 400 · invalid_json

Request body is not valid JSON

Cause. The request says it is application/json but the body could not be parsed.

What to do. Check quotes and trailing commas, and that you send one JSON object. With curl use --data-binary or -d with single quotes around the JSON.

{
  "error": {
    "type": "invalid_request",
    "message": "Invalid JSON body.",
    "code": "invalid_json",
    "docs_url": "https://audiolab.tools/docs/errors#invalid_json"
  }
}

HTTP 400 · missing_input

No audio in the request

Cause. The request has neither a URL, nor an objectPath, nor an audio body.

What to do. Send {"url": "https://..."}, or {"objectPath": "..."} from the signed-upload route, or the audio itself with an audio/* Content-Type (small files only).

{
  "error": {
    "type": "invalid_request",
    "message": "Provide { \"url\": \"…\" }, { \"objectPath\": \"…\" }, or a raw audio body.",
    "code": "missing_input",
    "docs_url": "https://audiolab.tools/docs/errors#missing_input"
  }
}

HTTP 400 · invalid_parameter

A parameter is not valid

Cause. An argument has a value we do not accept: an unknown profile, an unknown target, a target "custom" without numeric lufs and tp, or an endpoint a batch does not support.

What to do. Read the message: it names the parameter and lists the valid values. The OpenAPI document (/openapi.yaml) has the full list per endpoint.

{
  "error": {
    "type": "invalid_request",
    "message": "unknown profile: podcast, expected one of basic, voice, master, provenance, dataset, environment, broadcast, loop",
    "code": "invalid_parameter",
    "docs_url": "https://audiolab.tools/docs/errors#invalid_parameter"
  }
}

HTTP 400 · batch_too_large

Too many files in one batch

Cause. A batch takes at most 20 files per call.

What to do. Split the list into groups and send one call per group. Each group counts as one call per file against your monthly allowance.

{
  "error": {
    "type": "invalid_request",
    "message": "Batch too large: max 20 items per call. Split into smaller batches.",
    "code": "batch_too_large",
    "docs_url": "https://audiolab.tools/docs/errors#batch_too_large"
  }
}

HTTP 400 · upload_not_found

Uploaded file not found

Cause. The objectPath is malformed, belongs to another key, or the upload is gone: uploads are removed within the hour.

What to do. Upload the file again through the signed-upload route and use the objectPath within the hour. A path only works with the key that uploaded it.

{
  "error": {
    "type": "invalid_request",
    "message": "Uploaded file not found or expired. Re-upload and try again.",
    "code": "upload_not_found",
    "docs_url": "https://audiolab.tools/docs/errors#upload_not_found"
  }
}

HTTP 404 · unknown_endpoint

Unknown endpoint

Cause. The path after /v1/ is not one of the endpoints.

What to do. Check the path against /openapi.yaml. The analysis routes are mixlab/analyze, mixlab/check-target, mixlab/timeseries, mixlab/spectrum, voicelab/qa, voicelab/segments, signallab/index, signallab/sample and analyze/profile.

{
  "error": {
    "type": "not_found",
    "message": "unknown endpoint: mixlab/analyse",
    "code": "unknown_endpoint",
    "docs_url": "https://audiolab.tools/docs/errors#unknown_endpoint"
  }
}

HTTP 405 · method_not_allowed

Use POST (or GET on /v1/usage)

Cause. The analysis routes only answer POST requests, and /v1/usage only answers GET.

What to do. Send a POST to an analysis route and a GET to /v1/usage. A GET in a browser address bar on an analysis route shows this error.

{
  "error": {
    "type": "method_not_allowed",
    "message": "Use POST.",
    "code": "method_not_allowed",
    "docs_url": "https://audiolab.tools/docs/errors#method_not_allowed"
  }
}

HTTP 500 · storage_unavailable

Storage not available

Cause. We could not read your uploaded file from storage, or storage is not reachable right now. This is on our side. The response is a plain 500: the details are logged, never sent to you, and this code tells you where it went wrong.

What to do. Try again in a minute. If it keeps failing, email support@audiolab.tools with the time of the request.

{
  "error": {
    "type": "analysis_error",
    "message": "Internal analysis error.",
    "code": "storage_unavailable",
    "docs_url": "https://audiolab.tools/docs/errors#storage_unavailable"
  }
}

HTTP 500 · analysis_error

Something went wrong on our side

Cause. The analysis failed for a reason inside our service. The details are logged on our side and never sent to you.

What to do. Try again once. If the same file fails twice, email support@audiolab.tools with the time of the request and, if you can, the file.

{
  "error": {
    "type": "analysis_error",
    "message": "Internal analysis error.",
    "code": "analysis_error",
    "docs_url": "https://audiolab.tools/docs/errors#analysis_error"
  }
}

MCP · missing_api_key

No API key configured (MCP server or Python client)

Cause. The client has no AudioLab key. For the MCP server: the AUDIOLAB_API_KEY environment variable is empty, or the client did not send a bearer key to the remote endpoint. For the Python client: neither api_key nor the AUDIOLAB_KEY environment variable is set, and the call needs a key (usage, a batch, an upload of a file over 4 MB).

What to do. Make a free key on /account and put it in the MCP client configuration as shown on /connect, or pass api_key=... to the Python client or set AUDIOLAB_KEY.

MCP · api_timeout

The API took too long (MCP server or Python client)

Cause. The MCP server or the Python client waited for the API and gave up. Long files and busy moments can do this.

What to do. Try again, or analyse a shorter section of the file. The Python client waits 330 seconds by default (timeout=...).

MCP · api_unreachable

The API could not be reached (MCP server or Python client)

Cause. The MCP server or the Python client could not connect to audiolab.tools: no network, a firewall, or a proxy in between.

What to do. Check that the machine can open https://audiolab.tools/v1 and that no proxy blocks it. Check https://audiolab.tools/status.

MCP · invalid_input

The call is missing something (MCP server or Python client)

Cause. The MCP tool needs a URL or a local path to an audio file and got neither, or got both. The Python client was given something that is not a public URL or the path of a file it can read, a file that is empty, or a base_url that is not https.

What to do. Give exactly one of url or path (path works only with the local MCP server). In Python give a public https URL or the path of a file you can read.