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

# Troubleshooting

> Common errors, rate limits, and debugging tips

## API Error Format

All non-validation errors return a consistent envelope. The machine-readable
field is `type` (stable PascalCase), not a SCREAMING\_SNAKE `code`:

```json theme={null}
{
  "success": false,
  "status": 404,
  "error": {
    "message": "bucket not found",
    "type": "NotFoundError",
    "code": "optional_string",
    "details": {}
  }
}
```

Request-validation errors (`422`) use FastAPI's shape instead:

```json theme={null}
{
  "detail": [
    { "loc": ["body", "bucket_schema"], "msg": "field required", "type": "value_error.missing" }
  ]
}
```

## Common Errors

| Type                                   | Status | Cause                                                    | Fix                                                                                |
| -------------------------------------- | ------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `ValidationError`                      | 422    | Missing or invalid fields                                | Check required fields in the [API reference](https://api.mixpeek.com/docs/swagger) |
| `AuthenticationError`                  | 401    | Invalid, missing, or revoked API key                     | Verify the `Authorization: Bearer <key>` header                                    |
| `UnauthorizedError` / `ForbiddenError` | 403    | Missing/wrong `X-Namespace`, or insufficient permissions | Check the `X-Namespace` header matches the resource you're calling                 |
| `QuotaExceededError`                   | 403    | Plan usage/quota exceeded                                | See [Rate limits & quotas](/operations/rate-limits-quotas)                         |
| `NotFoundError`                        | 404    | Resource doesn't exist                                   | Verify the ID and namespace                                                        |
| `TooManyRequestsError`                 | 429    | Too many requests                                        | Back off and retry with exponential delay (respect `Retry-After`)                  |
| `ProcessingError`                      | 500    | Processing error in engine                               | Check task details for the specific failure reason                                 |

<Note>
  **401 vs 403 — they mean different things.** A **401 `AuthenticationError`** means the API key itself is bad (missing, malformed, or revoked). A **403** means the key is valid but the request isn't allowed: either the `X-Namespace` header is missing/doesn't match the resource (`UnauthorizedError`/`ForbiddenError`), or you've exceeded a plan quota (`QuotaExceededError`). Match the `type` field in the response body — not just the status code — to the fix.
</Note>

## Rate Limits

| Tier       | Requests/min | Concurrent tasks |
| ---------- | ------------ | ---------------- |
| Free       | 60           | 5                |
| Pro        | 600          | 50               |
| Enterprise | Custom       | Custom           |

When you hit a 429, the response includes `Retry-After` header with seconds to wait.

## Debugging Checklist

### Objects not processing

1. Check batch status: `GET /v1/buckets/{bucket_id}/batches/{batch_id}`
2. Check task status: `GET /v1/tasks/{task_id}`
3. Verify the collection's `feature_extractor` matches the bucket schema's blob types
4. Check for failed documents: `GET /v1/buckets/{bucket_id}/batches/{batch_id}/failed-documents`

### Retriever returning zero results

Zero results almost always trace to one of these — check in order:

| Likely cause                          | How to confirm                                                                                                                                     | Fix                                                                                                                                                          |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Documents aren't indexed yet**      | `GET /v1/tasks/{task_id}` — did the batch reach `COMPLETED`? `POST /v1/collections/{id}/documents/list` — are there any docs?                      | Wait for the batch to reach `COMPLETED` / `COMPLETED_WITH_ERRORS` before querying                                                                            |
| **Wrong `feature_uri`** (most common) | A mismatched URI matches nothing and returns 0 **silently** — feature\_search attaches a note to the response `warnings` array instead of erroring | `GET /v1/collections/{id}` → copy `vector_indexes[].feature_uri` exactly; see [Find your feature\_uri](/processing/features#find-your-feature_uri-to-search) |
| **Filter or threshold too strict**    | Temporarily remove `attribute_filter` stages and any `score_threshold` / `min_score`, then re-run                                                  | Loosen the filter or lower the threshold, then re-tighten                                                                                                    |
| **Wrong `collection_identifiers`**    | The retriever points at a collection that has no matching documents                                                                                | Set `collection_identifiers` to the collection you actually ingested into                                                                                    |
| **Empty query input**                 | An empty `inputs` value yields an empty query embedding → empty results                                                                            | Pass a non-empty query in `inputs`                                                                                                                           |

Then use the [explain endpoint](/api-reference/retrievers/explain-retriever-execution-plan) to see the execution plan and per-stage candidate counts.

### Poor retrieval quality

1. Check if the right extractor is being used for your query type (text query → text embedding, image query → visual embedding)
2. Add a reranking stage to improve precision
3. Review the execution trace for score distributions
4. Consider adding more retriever stages (filters, MMR for diversity)

### Slow processing

1. Video processing time scales with duration — 1 min video ≈ 1-2 min processing
2. Use batch processing for bulk imports instead of single-object ingestion
3. Check for resource contention: `GET /v1/tasks?status=PROCESSING`

## FAQ

**Can I use multiple feature extractors on the same data?**
Yes — create multiple collections pointing to the same bucket, each with a different extractor.

**How do I re-process documents after changing a collection's extractor?**
Create a new batch with the same objects and submit it. New documents replace old ones.

**What file formats are supported?**
Video (MP4, MOV, AVI, WebM), Images (JPG, PNG, WebP, GIF), Audio (MP3, WAV, M4A, FLAC), Documents (PDF, DOCX, TXT, HTML).

**How do I delete all data in a namespace?**
Delete the namespace: `DELETE /v1/namespaces/{namespace_id}`. This removes all buckets, collections, retrievers, and documents.

**Is there a size limit for uploads?**
Default: 500MB per file. Enterprise plans support larger files. Use URL references for files already in cloud storage.

[Contact support →](https://mixpeek.com/contact)