Developers / Errors
Error codes
Every TrackScore.AI™ API error uses one envelope: an error object with a stable machine-readable code, a human-readable message, the offending param when known, a doc_url pointing at this page when a docs anchor applies, and the request_id echoed in the X-Request-Id header. Match on code, never on message text.
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_credits",
"message": "You have 0 credits remaining.",
"param": null,
"doc_url": "https://trackscore.ai/developers/errors#insufficient_credits",
"request_id": "req_9f2c..."
}
}The request body is malformed or a field failed validation.
Resolve: Check error.message and error.param, fix the field, and retry.
A required field or header is absent, for example the Idempotency-Key header on POST /v1/analyses.
Resolve: Send the missing parameter named in error.param.
The byte upload never completed, so the analysis could not run.
Resolve: Retry the upload step within the token window, or submit again. The credit is automatically restored.
The Authorization bearer key is missing, malformed, or revoked.
Resolve: Send Authorization: Bearer ts_live_… with an active key from the Developer console.
The account behind this key has no credits remaining, so the analysis was not started.
Resolve: Top up or upgrade from the dashboard. No credit is spent on a rejected call.
The analysis owner has not enabled public embedding for this analysis.
Resolve: The owner can enable the embed badge from the analysis page. Public badge requests for disabled or unknown analyses return 404.
The key's account does not include API access. Self-serve API access requires a Pro or Studio plan.
Resolve: Upgrade to Pro or Studio, or contact us about partner access.
No analysis with that id is visible to this key. Unknown ids and ids owned by other accounts look identical.
Resolve: Use the id returned by POST /v1/analyses with the same account's key.
This Idempotency-Key was already used with a different request body.
Resolve: Use a fresh Idempotency-Key for a new request; reuse a key only to retry the identical request.
An identical request with this Idempotency-Key is still being processed.
Resolve: Wait briefly and retry; you will receive the original response when it completes.
The uploaded file exceeds the size or duration limit (20 minutes).
Resolve: Trim or re-export the track under the limits, then submit again.
The uploaded file exceeds the size limits, enforced at the upload step (200 MB, with tighter caps for compressed formats).
Resolve: Export a smaller file. WAV and AIFF up to 200 MB, MP3 up to 48 MB, FLAC up to 140 MB.
The audio could not be decoded, for example a corrupted file or a compressed codec inside a WAV container.
Resolve: Re-export as a standard WAV or MP3 and resubmit. The credit is automatically restored.
The shared analysis engine is at capacity right now.
Resolve: Retry with exponential backoff; capacity frees up within minutes.
This key already has its maximum number of analyses in flight (default 1).
Resolve: Wait for the in-flight analysis to complete before submitting the next one.
The key's daily analysis quota is exhausted.
Resolve: Wait for the window to reset, or contact us about partner quotas.
Too many requests in the per-minute window for this key (default 30/min).
Resolve: Honor the Retry-After header and back off. Limits are per key and shown in your console.
An unexpected error on our side. Nothing was charged unless an analysis actually started.
Resolve: Retry with the same Idempotency-Key; if it persists, contact support with the request_id.
The analysis engine failed unexpectedly while processing the track.
Resolve: Submit the track again. The credit is automatically restored on failure.
Last updated 2026-07-20 · Codes marked "embedded" also appear inside a failed analysis object's error field.