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 | Key scope or org access denied |
404 | NOT_FOUND | Resource 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_PERMISSIONSCheck the key's scope and the org's grants. Collection-scoped keys cannot call /api/v1/tools/*; use an org-wide key for tools.
404NOT_FOUNDVerify the collection or tool name exists and your org has access. Names are case-sensitive. If a tool was just disabled, refresh the docs page.
422VALIDATION_ERRORCheck the field path returned in the error. For Search, ensure `collection` and `query` are present. For Tools, the body must match the tool's inputSchema (visible on the tool's docs page).
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 and spend are tracked per API key. View totals on the Billing page in the dashboard.