> ## 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 the same envelope. `details.validation_errors`
lists every field that failed, and the message names the first one:

```json theme={null}
{
  "success": false,
  "status": 422,
  "error": {
    "message": "Validation error: querry: 'querry' is not a field here; accepted: options, query",
    "type": "ValidationError",
    "details": {
      "validation_errors": [
        {
          "type": "extra_forbidden",
          "location": ["body", "querry"],
          "message": "Extra inputs are not permitted",
          "accepted_keys": ["options", "query"]
        }
      ]
    }
  }
}
```

## Unknown keys in a request body

Until 2026-11-02, a key that a request body does not declare is accepted and
ignored, and the response tells you about it. A JSON object response gets a
`warnings` entry per key, and every response carries the `X-Mixpeek-Unknown-Keys`
header listing them:

```json theme={null}
{
  "warnings": [
    {
      "resource": "request_body",
      "id": "querry",
      "reason": "'querry' is not a field of this request and was ignored. From 2026-11-02 a request carrying it is refused with 422.",
      "next_step": "Remove it. Accepted here: options, query"
    }
  ]
}
```

From 2026-11-02 the same request is refused with the `422` above, with
`"type": "extra_forbidden"`. The error's `accepted_keys` lists what the body
takes where you sent the key, so remove the key or rename it to one of those.
The official SDKs send only declared keys, so this affects hand-written requests.
Each request body in the [API reference](https://api.mixpeek.com/docs) carries
the date under `x-unknown-keys`.

## Common Errors

| Type | Status | Cause | Fix |
| - | - | - | - |
| `ValidationError` | 422 | Missing or invalid fields | Check required fields in the [API reference](https://api.mixpeek.com/docs) |
| `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 |
| `PlanRequiredError` | 403 | Workspace has not picked a plan yet, so billable work is gated | [Choose a plan](https://studio.mixpeek.com/signup/plan). `GET /v1/organizations` returns `requires_plan: true` while gated — see [Billing](https://docs.mixpeek.com/docs/platform/billing.md) |
| `QuotaExceededError` | 403 | Plan usage/quota exceeded | See [Rate limits & quotas](https://docs.mixpeek.com/docs/operations/rate-limits-quotas.md) |
| `PaymentRequiredError` | 402 | Mixpeek's monthly spending stop is holding new paid work for every organization | Nothing to change on your side: it lifts when Mixpeek lifts it or on `details.lifts_on`. Search keeps working. See [Budgets](https://docs.mixpeek.com/docs/platform/budgets.md) |
| `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`) |
| `DependencyUnavailable` | 503 | A store the request needed (database or cache) could not be reached. Nothing was changed. `details.resource` names it | Retry after the `Retry-After` header's seconds |
| `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`), you've exceeded a plan quota (`QuotaExceededError`), or the workspace has not chosen a plan yet (`PlanRequiredError`). A new workspace hits `PlanRequiredError` first: it blocks namespace creation and any billable work until you pick a plan. Match the `type` field in the response body — not just the status code — to the fix.

## 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`

### A list returns an empty page

`GET /v1/collections`, `GET /v1/buckets`, and `GET /v1/retrievers` return `200` with an empty page when `X-Namespace` does not resolve for your key. So do the matching `POST .../list` routes. A new workspace's first call is not an error.

1. Read the `warnings` array in the response body. An entry with `"resource": "namespace"` and `"reason": "unresolved"` means the namespace did not resolve. Its `id` is the value you sent and its `next_step` says what to do.
2. The same condition sets the response header `X-Namespace-Unresolved: true`, for callers that read headers.
3. The entry and the header appear when the namespace does not exist and when it belongs to another organization. The two cases look the same.
4. List your namespaces with `GET /v1/namespaces`, then send one of those ids in `X-Namespace`.
5. An empty `warnings` array and no header mean the namespace resolved. The empty page is the true answer.

```json theme={null}
{
  "results": [],
  "warnings": [
    {
      "resource": "namespace",
      "id": "ns_does_not_exist",
      "reason": "unresolved",
      "next_step": "This namespace does not exist for your API key, so the empty list is not its contents. List your namespaces with GET /v1/namespaces and send one of their ids in X-Namespace."
    }
  ]
}
```

### 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](https://docs.mixpeek.com/docs/processing/features.md#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](https://docs.mixpeek.com/docs/api-reference/retrievers/explain-retriever-execution-plan.md) 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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.