Errors

The Finetuning.ai API uses standard HTTP status codes and returns consistent error responses.

Error response format

All errors follow the format:

{
  "error": {
    "code": "...",
    "message": "..."
  }
}

Code	Status	Description
`MISSING_API_KEY`	401	X-API-Key header was not provided
`INVALID_API_KEY`	401	API key is malformed, revoked, or does not exist
`ACCOUNT_DELETED`	401	The account this API key belongs to has been deleted
`PRO_PLAN_REQUIRED`	403	Your subscription does not include API access
`RATE_LIMITED`	429	Too many requests on a read endpoint — wait and retry (60/min/user)
`GENERATION_RATE_LIMITED`	429	Too many calls to a create endpoint — wait and retry (10/min/user, counted separately for music, instrumental, and sound effects)
`VALIDATION_ERROR`	400	Request body is missing or has invalid fields
`NOT_READY`	400	The work is not `completed` yet — certificates only exist for finished generations
`PAID_PLAN_REQUIRED`	403	The feature needs a paid plan — generation certificates require a Plus, Pro, or Lifetime plan, as do Reimagine and Remove vocals
`ADD_FAILED`	400	None of the tracks in a bulk playlist add could be added — see `details`
`MOVE_FAILED`	400	None of the tracks in a bulk playlist move could be moved — see `details`
`MONTHLY_LIMIT_REACHED`	402	No generations remaining this month
`QUEUE_FULL`	429	Too many generations in progress
`DAILY_LIMIT_REACHED`	429	The shared daily sound-effect cap has been reached — try again tomorrow
`GENERATION_FAILED`	500	Generation queue submission failed
`NOT_FOUND`	404	Resource not found
`INTERNAL_ERROR`	500	Unexpected server error

These codes come from the Reimagine and Remove vocals endpoints. Everything above applies to them too.

Code	Status	Description
`ATTESTATION_REQUIRED`	400	The rights confirmation is missing or out of date
`LYRICS_REQUIRED` / `LYRICS_TOO_LONG`	400	Reimagine: no lyrics, or more than the song's length allows
`INSUFFICIENT_CREDITS`	402	Not enough credits for the render. Also returned by `POST /v1/songs/uploads` for Reimagine when there's no credit for the transcription (1)
`PRIVATE_ONLY`	403	Reimagine / Remove vocals tracks can't be made public, shared or certified
`TRANSCRIPT_NOT_READY` / `TRANSCRIPT_REQUIRED`	409	Reimagine: we haven't finished listening to the song, or haven't been asked to
`CATALOGUE_MATCH`	409	The upload matches a commercial release and was deleted
`UPLOAD_EXPIRED`	410	The upload's 24 hours are up
`FILE_TOO_LARGE`	413	Upload over 20 MB
`UNSUPPORTED_FORMAT` / `UNREADABLE_AUDIO`	415	Not an MP3 or WAV we can read
`SONG_TOO_LONG` / `SONG_TOO_SHORT` / `SOURCE_UNAVAILABLE` / `TRIM_FAILED`	422	Upload problems — see POST /v1/songs/uploads
`UPLOAD_LIMIT`	429	More than 10 song uploads in an hour or 30 in 24 hours; see `Retry-After`
`FEATURE_COMING`	503	Remove vocals is switched off for now; nothing was charged

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is malformed, revoked, or does not exist"
  }
}

Fix: Ensure you're using the X-API-Key header (not Authorization: Bearer). Double-check for extra whitespace or newlines in your key.

{
  "error": {
    "code": "MONTHLY_LIMIT_REACHED",
    "message": "No generations remaining this month"
  }
}

Fix: Upgrade your plan or wait for your monthly limit to reset at finetuning.ai/dashboard.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "duration must be between 5 and 210 seconds"
  }
}

Fix: Check the message field for details on which fields are invalid.

If a generation stays in processing for more than 5 minutes, it may have failed silently. Contact support.

If you're encountering errors not listed here, visit the Support page.