Mixpeek returns a consistent JSON error envelope for API errors and structured codes for WebSocket failures. This guide shows common error types, how to diagnose them, and recommended fixes.

​
Canonical error envelope

{
  "success": false,
  "status": 404,
  "error": {
    "message": "Resource not found",
    "type": "NotFoundError",
    "details": {
      "resource": "collection",
      "id": "col_missing"
    }
  }
}
  • success: always false on errors
  • status: HTTP status code
  • error.type: stable, machine‑readable error class
  • error.details: optional context for debugging

​
Common API errors

400 BadRequestError

Malformed input, unsupported parameters, invalid state transitions

422 ValidationError

Pydantic validation failed; check field names and types

404 NotFoundError

Resource or route not found (IDs, names, or paths)

409 AlreadyExistsError

Unique constraint conflict (e.g., duplicate names per namespace)

429 TooManyRequestsError

Rate limit exceeded; back off and retry later

403 UnauthorizedError

Missing/invalid permissions, tier/credit checks, or auth failures

500 InternalServerError

Unexpected server error; retry, then contact support if persistent

503 InferenceServiceUnavailableError

Inference backend unavailable; retry with backoff or failover

​
Domain‑specific errors

  • ProcessingError · FeatureExtractionError · SchemaValidationError
  • StorageError · S3StorageError
  • QdrantError · MongoDBError
  • NotEnabledError · NotImplementedError · UnavailableError
  • RaySubmissionError · TimeoutError (408)
These include a descriptive message and may include details to pinpoint the failing phase (extraction, storage, database, engine dispatch).

​
WebSocket errors

{ "code": 4001, "type": "WebSocketAuthenticationError", "message": "WebSocket authentication failed" }
{ "code": 4004, "type": "WebSocketTaskNotFoundError", "message": "Task not found" }
{ "code": 4000, "type": "WebSocketInternalError", "message": "Internal WebSocket server error" }
  • 4001: Authentication failure
  • 4004: Referenced task not found/expired
  • 4000: Generic internal WebSocket error

​
Quick diagnosis

1

Check headers

Ensure Authorization and X-Namespace are set where required
2

Validate inputs

Compare body against API reference schemas; fix types/paths
3

Confirm resource IDs

Verify namespace, collection/retriever/taxonomy IDs or names
4

Review limits

For 429, see rate limits and backoff strategies
5

Inspect logs

Correlate request IDs across API/Engine; check recent exceptions

​
Examples

​
Validation error (422)

{
  "success": false,
  "status": 422,
  "error": {
    "message": "Validation error",
    "type": "ValidationError",
    "details": {
      "validation_errors": [
        { "type": "string_type", "location": ["body","collection_name"], "message": "Input should be a valid string" }
      ]
    }
  }
}

​
Rate limit exceeded (429)

{
  "success": false,
  "status": 429,
  "error": { "message": "Rate limit exceeded", "type": "TooManyRequestsError", "details": {"api_name": "search"} }
}

​
Not found (404)

{
  "success": false,
  "status": 404,
  "error": { "message": "Resource not found", "type": "NotFoundError" }
}

​
Resolution tips

  • 400/422: Recheck body shape and field paths; align with OpenAPI
  • 403: Confirm API key permissions and account tier/credits
  • 404: Verify identifiers and namespace context; ensure resources exist
  • 408/429: Exponential backoff and retries; reduce request rate/size
  • 5xx: Retry with jitter; if persistent, capture request ID and contact support

​
See also

Troubleshooting: Limits

Understand rate limits and quotas by tier

Health API

Check service readiness and dependency status