Error Handling
Common Status Codes
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. |
| 401 | Unauthorized | Missing or invalid authentication credentials, or insufficient user permissions. |
| 402 | Payment Required | Valid request, but the account needs a balance top-up or a valid payment method. |
| 403 | Forbidden | The authenticated user lacks the necessary permissions for the requested resource. |
| 404 | Not Found | The requested resource doesn't exist or cannot be found at the given URL. |
| 422 | Validation Error | There was an issue with the request parameters. Check your input and retry. |
| 429 | Too Many Requests | The rate limit has been exceeded. The response may include retry timing info. |
| 500 | Internal Server Error | An unexpected error occurred on the server-side. Retry the request later. |
| 503 | Service Unavailable | The service is temporarily unavailable, likely due to maintenance or overload. Retry later. |
| 504 | Gateway Timeout | A server acting as a gateway or proxy did not receive a timely response from an upstream server. Possible network issues or overload. Retry later. |
Working With The SDKs
Our SDKs provide a great way for developers to interact with the Mixedbread API. Lets take a look at how to handle errors properly using the SDKs to ensure a good developer experience. Catching specific error types provided by the SDKs allows for more granular control and response logic.
Best Practices
Implementing robust error handling is crucial for a reliable application. Consider these best practices:
- Catch Specific Errors First (SDKs): When using the SDKs, always try to catch the most specific error types (like
AuthenticationError,RateLimitError, etc.) before falling back to the baseException/Error. - Always Check the Status Code: Before processing the response body, check the HTTP status code to determine if the request was successful.
- Implement Retries: For transient errors like
RateLimitError(HTTP 429),InternalServerError(HTTP 500),ServiceUnavailable(HTTP 503), andGatewayTimeout(HTTP 504), implement retry logic. Our SDKs allow configuring max retries automatically for certain errors. Consider using exponential backoff strategies. - Log Errors: Log detailed error information, including timestamps, the request parameters (be mindful of sensitive data), the full error message or stack trace, and response details. This is invaluable for debugging.
Debugging and Support
- For 4xx errors (Client Errors like 401, 403, 422), carefully review your request parameters, headers, authentication details, and permissions. The error response body often contains specific details.
- For 5xx errors (Server Errors like 500, 503, 504), these indicate a problem on the server-side. Check our status page for any known issues. If the problem persists, retry later.
If you encounter persistent errors or issues not covered here:
Rate Limiting
Documentation on API rate limits with tier-based quotas. Learn about request limits, how to handle rate limiting responses, and strategies for optimizing your API usage.
Vector Stores
API reference for managing and searching Mixedbread Vector Stores. This documentation covers all essential endpoints to work with vector stores and their associated files.
Last updated: June 11, 2025