Skip to main content
Every API error returns the same JSON envelope: 
{
  "success": false,
  "status": 404,
  "error": {
    "type": "NotFoundError",
    "message": "Resource not found",
    "details": { "resource": "collection", "id": "col_missing" }
  }
}
  • status is the HTTP status code.
  • type is a stable error class you can branch on.
  • details contains structured context (optional).

​
Frequent Errors & Fixes

HTTPError TypeTypical CauseResolution
400BadRequestErrorInvalid query parameters, unsupported combinationsCompare request with OpenAPI schema; remove unknown keys
401UnauthorizedErrorMissing/invalid API keyProvide Authorization: Bearer <api_key>
403ForbiddenError / NotEnabledErrorFeature disabled or wrong permission tierCheck account plan or API key scopes
404NotFoundErrorResource ID/name incorrect, wrong namespaceVerify IDs and X-Namespace; list resources to confirm
409AlreadyExistsErrorDuplicate name within namespaceChoose unique names or delete existing resource
422ValidationErrorBody schema mismatchInspect validation_errors in details; fix types/paths
429TooManyRequestsErrorRate limit exceededThrottle requests, introduce exponential backoff
500InternalServerErrorUnexpected server errorRetry with jitter; capture request_id for support
503InferenceServiceUnavailableErrorRay Serve deployment unavailableRetry; check Ray dashboard for replica health

​
Domain-Specific Errors

  • ProcessingError, FeatureExtractionError – Engine failed during extraction; inspect task logs (/v1/tasks/{id}) and Ray job output.
  • StorageError, MongoDBError, QdrantError – Underlying datastore unavailable or returned failure; verify connection strings and service health.
  • TimeoutError, RaySubmissionError – Engine job submission failed or timed out; check Ray head logs and job queue depth.

​
Debugging Checklist

  1. Headers – Confirm both Authorization and X-Namespace are present where required.
  2. Schema – Validate request against /api-reference/... examples; pay attention to recent breaking changes (e.g., feature_extractor singular).
  3. Resource existence – Use list endpoints to confirm IDs. Names are namespace-scoped; duplicates across namespaces are allowed.
  4. Task status – For async operations (batches, clustering, taxonomy), poll /v1/tasks/{task_id} or the resource until COMPLETED.
  5. Health – Call /v1/health if you suspect dependency failures.
  6. Logs – Check API logs (request ID) and Ray job logs (additional_data.job_id in task response) for stack traces.
  7. Webhooks – If downstream systems disagree, inspect webhook events (collection.documents.written), which persist until delivered.

​
Error Examples

​
Validation Error (422)

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

​
Rate Limit (429)

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

​
Engine Failure

{
  "success": false,
  "status": 500,
  "error": {
    "type": "ProcessingError",
    "message": "Extractor text_extractor failed",
    "details": {
      "batch_id": "bat_abc123",
      "extractor": "text_extractor@v1",
      "job_id": "ray_job_456"
    }
  }
}
Use job_id to fetch Ray logs: ray job logs ray_job_456.

​
Retry Guidance

  • Idempotent GET/POST: safe to retry with exponential backoff (jitter).
  • Batch submissions: multiple submissions of the same batch are ignored (skip_duplicates).
  • Mutations (create/update): ensure client retries include the same idempotency keys or check resource existence before resubmitting.

​
When to Contact Support

  • Persistent 5xx errors with identical inputs.
  • Inference disruptions across models (Ray Serve unreachable).
  • Data consistency issues between MongoDB and Qdrant.
  • Feature flags or endpoints missing from your plan (NotEnabledError).
Provide the request_id (from response headers), namespace_id, and relevant resource IDs to accelerate investigation.