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. |
| 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 Practices
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 Examples
Pagination
Understanding cursor-based pagination across Mixedbread API endpoints. Learn how to navigate through large result sets efficiently using cursors, handle pagination parameters, and implement robust pagination logic.
List Vector Stores
List all vector stores with optional search.
Last updated: September 10, 2025