Every error is typed, so your code can catch exactly the case it cares about. A “not in your documents” answer is not an error; it is a normal result with not_covered: true.
| Exception | When it happens | What to do |
|---|---|---|
AuthError | Missing or invalid API key. | Check SEARCHCANDY_API_KEY is set and current. |
StoreAccessError | That graph is not yours, or the id is wrong. | Check the store name; keys only see their own account's graphs. |
RequestError | The request itself is malformed. | The message names the field to fix. |
GraphNotReadyError | The graph is busy indexing a change. | Retry shortly. The SDK already waits politely on submits. |
IngestFailedError | A batch of documents did not go in. | Carries job_id plus which documents remain; resend those. |
BudgetPausedError | The daily indexing budget was reached. | Never retried automatically. Resumes next day, or talk to us. |
VersionNotFound | That version number does not exist. | List versions to see the real timeline. |
StoreUnversioned | A graph built before versioning existed. | Re-ingest into a new graph, or ask us to rebuild it. |
DraftNotFound / DraftClosed | The named draft is missing or was closed. | Open it again from the version you want. |
DraftBehind | The graph moved on while your draft was open. | It lists the versions you would override; pass accept_behind=True to force. |
NameTaken | A draft with that name already exists. | Pick another name. |
GraphIncomplete | The graph loaded less than it saved. Damage. | Not retryable. We restore from backup; contact us. |
EmbeddingModelMismatch | The graph was read with a different model than built it. | Configuration problem on our side. Contact us. |
YourEmbeddingEndpointError | Your own embedding server failed. | Check your endpoint; rotate credentials in Settings if needed. |
SearchCandyServerError | Something failed on our side. | Quote the request_id to support; we can trace every request. |
SearchCandyUnavailable | Network failure after retries. | Check connectivity and try again. |
Every server error carries a request_id. Include it when you write to us and we can trace the exact request.