Error Handling

Common Status CodesLink to section

Understanding the status codes returned by the API is the first step in handling responses correctly. Here are the most common codes you might encounter:

Code	Meaning	Description
200	OK	Request successful. The response contains the requested data.
201	Created	Resource successfully created. Common for POST requests.
400	Bad Request	Malformed request or missing required parameters.
401	Unauthorized	Invalid, expired, or missing API key.
402	Payment Required	Insufficient balance. Top up your account to continue.
403	Forbidden	Valid credentials but insufficient permissions for this resource.
404	Not Found	The requested resource doesn't exist.
409	Conflict	Operation conflicts with current resource state.
422	Unprocessable Entity	Request format is correct but cannot be processed.
429	Rate Limit Exceeded	Too many requests. Wait before retrying.
500	Internal Server Error	Unexpected server error. Retry after a brief wait.
503	Service Unavailable	Service temporarily down for maintenance or overloaded. Retry later.

Best PracticesLink to section

Build reliable applications with these error handling patterns:

Catch specific errors first - Handle specialized error types before generic exceptions
Check status codes early - Validate response status before processing the body
Implement smart retries - Use exponential backoff for transient errors

Code ExamplesLink to section

Error Handling

from mixedbread import (
  Mixedbread,
  AuthenticationError,
  RateLimitError
)

mxbai = Mixedbread(api_key="YOUR_API_KEY")

try:
  res = mxbai.stores.search(
      query="How to implement authentication?",
      store_identifiers=["docs", "knowledge-base"],
      top_k=5
  )

  for chunk in res.data:
      print(f"Score: {chunk.score:.4f}, File: {chunk.filename}")

  except AuthenticationError as e:
      print(f"Authentication failed: {e.message}")

  except RateLimitError as e:
      print(f"Rate limit exceeded: {e.message}")

  except Exception as e:
      print(f"Unexpected error: {e}")

Error Handling

Common Status CodesLink to section

Best PracticesLink to section

Code ExamplesLink to section

On this page