Error Reference
The API uses standard HTTP status codes and returns structured error responses to help you diagnose issues.
Error Response Format
All error responses follow this structure:
code — Machine-readable error code. Use this for programmatic error handling.
message — Human-readable description. Safe to display to end users.
request_id — Unique request identifier. Include this when contacting support.
Error Codes
| Status | Code | Meaning |
|---|---|---|
200 | — | Success |
401 | AUTHENTICATION_REQUIRED | Invalid or missing API key |
403 | INSUFFICIENT_PERMISSIONS | No access to requested collection |
404 | NOT_FOUND | Collection not found |
422 | VALIDATION_ERROR | Invalid request body |
429 | RATE_LIMITED | Rate limit exceeded |
500 | INTERNAL_ERROR | Internal server error |
Troubleshooting
401AUTHENTICATION_REQUIREDCheck that the Authorization header is present and the key is valid. Keys start with sk_live_.
403INSUFFICIENT_PERMISSIONSThe API key doesn't have access to this collection. Use an org-wide key or add the collection to the key's scope.
404NOT_FOUNDVerify the collection name exists. Names are case-sensitive.
422VALIDATION_ERRORCheck required fields (collection, query). Ensure query is under 1000 characters and limit is between 1-30.
429RATE_LIMITEDWait for the Retry-After period and implement exponential backoff. See Rate Limits for details.
500INTERNAL_ERRORAn unexpected error occurred. Retry the request. If it persists, contact support with the request_id.
Usage is tracked per API key. View statistics on your Usage page in the dashboard.