Troubleshooting

API Error Format

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

{
  "success": false,
  "status": 404,
  "error": {
    "message": "bucket not found",
    "type": "NotFoundError",
    "code": "optional_string",
    "details": {}
  }
}

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

{
  "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
`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
`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

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.

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

Check batch status: GET /v1/buckets/{bucket_id}/batches/{batch_id}
Check task status: GET /v1/tasks/{task_id}
Verify the collection’s feature_extractor matches the bucket schema’s blob types
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
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 to see the execution plan and per-stage candidate counts.

Poor retrieval quality

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

Slow processing

Video processing time scales with duration — 1 min video ≈ 1-2 min processing
Use batch processing for bulk imports instead of single-object ingestion
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 →

​API Error Format

​Common Errors

​Rate Limits

​Debugging Checklist

​Objects not processing

​Retriever returning zero results

​Poor retrieval quality

​Slow processing

​FAQ

API Error Format

Common Errors

Rate Limits

Debugging Checklist

Objects not processing

Retriever returning zero results

Poor retrieval quality

Slow processing

FAQ