Errors - NanoClip API

The API returns standard HTTP status codes with a JSON error body.

{
  "detail": "Missing API key"
}

Common errors

Status	Meaning	Recovery
`400 Bad Request`	The request is syntactically valid JSON but violates an API rule.	Fix the invalid field and retry.
`401 Unauthorized`	The API key is missing or invalid.	Send `Authorization: Bearer $NANOCLIP_API_KEY`.
`402 Payment Required`	The workspace billing wallet is missing or has insufficient credits.	Add credits or finish billing setup, then retry the analysis request.
`403 Forbidden`	The key does not have the required scope.	Create or request a key with the needed scope.
`404 Not Found`	The project or command does not exist in the key’s workspace.	Check the ID and workspace.
`409 Conflict`	The operation conflicts with the current project state.	Complete the upload before analysis.
`413 Content Too Large`	The upload is larger than the configured maximum.	Use a smaller file or request a higher limit.
`415 Unsupported Media Type`	The upload `content_type` is not in the allowed set.	Use an allowed type — see Allowed upload content types.
`422 Unprocessable Entity`	Request body validation failed, or the analysis is not available for the source’s media kind (e.g. vision or retake-removal on an audio source).	Fix the payload per the API reference schema; audio sources support transcript only.
`429 Too Many Requests`	A request, project, or command limit was exceeded.	Back off and retry later.
`503 Service Unavailable`	Could not dispatch processing work.	Retry with backoff.

Failed analyses

A start request returns 202, but an analysis can still finish in status: failed. In that case the result endpoint’s error string carries the reason. Some failures are expected and return a specific, actionable message — for example, a source with no detectable speech (music-only or muted audio) fails with:

{ "error": "No speech was detected in this video." }

Unexpected internal faults return a failure reason in the same error field. For retake-removal this is a generic message with a support reference you can forward:

{ "error": "An internal error occurred. Please retry; if the problem persists, contact support with ref <id>." }

Upload state conflicts

Analysis commands require a completed source upload. If you start transcript, vision, or retake-removal analysis too early, the API returns:

{
  "detail": "Project upload must be completed before running analysis"
}

Complete the upload, then start the analysis command again.

Rate limits

When a limit is exceeded, the API returns:

{
  "detail": "Rate limit exceeded"
}

See limits for the current defaults.

Billing errors

When credit billing is enabled, transcript, vision, and retake-removal start requests can return:

{
  "detail": "Insufficient workspace credits"
}

or:

{
  "detail": "Workspace billing wallet is not ready"
}

The analysis is not queued until the workspace can be charged.

​Common errors

​Failed analyses

​Upload state conflicts

​Rate limits

​Billing errors

Common errors

Failed analyses

Upload state conflicts

Rate limits

Billing errors