> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanoclip.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand common API errors and how to recover.

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

```json theme={null}
{
  "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](/limits#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:

```json theme={null}
{ "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:

```json theme={null}
{ "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

See [limits](/limits) for the current defaults.

## Billing errors

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

```json theme={null}
{
  "detail": "Insufficient workspace credits"
}
```

or:

```json theme={null}
{
  "detail": "Workspace billing wallet is not ready"
}
```

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