Errors & troubleshooting
When a call fails, the response carries an error code. The tables below explain
each one by category.
Authentication errors
| Code | HTTP | Meaning & fix |
|---|
401 Unauthorized | 401 | API key is wrong, missing, or malformed. Ensure the header is Authorization: Bearer sk-nodaryx-…; or sign in to the console again. |
missing_runtime_metadata | 400 | Called with a bare master key that has no session metadata. Use an API key created in the console. |
Permission errors
| Code | HTTP | Meaning & fix |
|---|
MODEL_NOT_ALLOWED | 403 | Your account or key has no access to this model. See Permissions & model scope, or ask an admin to grant access. |
WEB_SEARCH_NOT_ENABLED | 403 | Web search is a beta capability not enabled for your account. Ask an admin to whitelist you. |
Balance errors
| Code | HTTP | Meaning & fix |
|---|
insufficient_credit | 402 | Out of balance. See Balance & usage, or ask an admin to grant test credit. |
Rate-limit errors
| Code | HTTP | Meaning & fix |
|---|
RATE_LIMITED | 429 | Rate limited (RPM/TPM or search frequency). Lower the call rate and retry later. |
parallel_limit_exceeded | 429 | Too many concurrent requests. Reduce requests in flight. |
File upload errors
| Code | HTTP | Meaning & fix |
|---|
FILE_TOO_LARGE | 400 | File exceeds 2 MB. Compress or split it before uploading. |
FILE_EMPTY | 400 | No extractable text (e.g. scanned PDF / image with no text). Use a text-based file. |
FILE_TEXT_DECODE_FAILED | 400 | File is corrupted or can't be parsed (e.g. encrypted PDF). Check the file and retry. |
QUERY_BLOCKED | 403 | A suspected secret (private key, token, etc.) was detected in the input and blocked. Remove sensitive content. |
Upstream / provider errors
| Code | HTTP | Meaning & fix |
|---|
PROVIDER_UNAVAILABLE | 503 | The upstream provider is temporarily unavailable. Retry later; if it persists, contact an admin. |
Still stuck?