> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/integrations-and-best-practices/troubleshooting.md). # Troubleshooting Most issues fall into one of a handful of patterns. Start with the error code table. If your problem isn't there, run the diagnostic flow at the bottom. ## Common errors and fixes | Error | Likely cause | Fix | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Bad API key, missing `Bearer` prefix, or wrong auth header for the endpoint | Check your key at [app.thegrid.ai/profile/api-keys](https://app.thegrid.ai/profile/api-keys). For the Consumption API, the header is `Authorization: Bearer YOUR_KEY`. For the Messages API beta, the header is `x-api-key: YOUR_KEY` (no `Bearer`). | | `402 Payment Required` | Insufficient credits or no available consumption tokens for the instrument | Add credits in the dashboard. Set up Auto-Reload to prevent this. If Auto Buy is buying tokens, retry after a short delay. `402` is retryable in this case. | | `404 Not Found` (model) | Invalid instrument string in `model` | Use one of [our nine instruments](/docs/instrument-specifications/current-instruments.md): `text-standard`, `text-prime`, `text-max`, `code-standard`, `code-prime`, `code-max`, `agent-standard`, `agent-prime`, `agent-max`. Model names like `gpt-5.2` or `claude-sonnet-4-6` return 404. | | `404 Not Found` (path) | Wrong base URL or doubled `/v1` | The base URL is `https://api.thegrid.ai/v1`. If your SDK auto-appends `/v1`, set the base URL to `https://api.thegrid.ai` instead. Check for `/v1/v1/` in the failing URL. | | `400` input or context length too long | Your tool packed a request larger than the instrument's window, usually because no max input or max output limit was configured | Set the maximum input tokens in your harness config (120K for Standard and Prime, 922K for Max), and keep the maximum output below the context window so input plus output fits. Tools that lack an input field derive the budget as context minus output, so set a real output cap. See [Best practices → Set the input and output token limits](/docs/integrations-and-best-practices/best-practices.md). | | `429 Too Many Requests` | Per-key or per-instrument rate limit hit | Back off and retry. Check the `Retry-After` header. Use exponential backoff with jitter. | | `500 Internal Server Error` | Transient service issue | Retry with exponential backoff. Failed requests are not billed. | | `503 Service Unavailable` | Balance replenishment in progress (Auto Buy active) | Retry after a short delay. By the second or third attempt the new tokens are usually available. | | Connection refused | Wrong base URL | Confirm `https://api.thegrid.ai/v1`. No trailing slash, no extra path segments, no typos. | | Hangs or no response | Network or proxy issue | Check your proxy or firewall. We use standard HTTPS on port 443. | | Streaming cuts off mid-response | Idle timeout on a proxy | Increase the idle timeout on whatever sits between your client and `api.thegrid.ai`. Some corporate proxies time out streaming connections at 30–60 seconds. | | `307 Temporary Redirect` not followed | Client doesn't follow redirects by default | For curl, add `-L`. Most SDKs follow redirects automatically. See [API reference → Request routing and redirects](/docs/api-reference/request-routing-and-redirects.md) for full details. | ## "Is it me or The Grid?" diagnostic flow Before assuming The Grid is down, walk through this: 1. **Check the status page.** Visit [status.thegrid.ai](https://status.thegrid.ai). If there's an active incident, it's not you. 2. **Test with curl.** Strip out your SDK and frameworks. If a plain curl request works, the issue is in your client code or config. ```bash curl https://api.thegrid.ai/v1/chat/completions \ -H "Authorization: Bearer YOUR_GRID_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "text-prime", "messages": [{"role": "user", "content": "ping"}] }' ``` If you get a normal response, your auth and network are fine. The bug is somewhere in your application. 3. **Check the auth header format.** A 401 usually means the header is wrong, not that the key is wrong. The full header for the Consumption API is `Authorization: Bearer YOUR_KEY` (literal word `Bearer`, then a space, then your key). For the Messages API beta, it's `x-api-key: YOUR_KEY` with no `Bearer` prefix. 4. **Check the base URL.** A 404 on what looks like a valid request usually means the URL is malformed. Common causes: trailing slash, doubled `/v1`, extra `/chat/completions` appended manually, or a typo in the host. Print the actual URL your SDK is hitting and compare it character-by-character to `https://api.thegrid.ai/v1/chat/completions`. 5. **Check the model string.** A 404 with the URL correct usually means the `model` parameter is wrong. Print what you're passing. It must be one of [our nine instruments](/docs/instrument-specifications/current-instruments.md). `text-prime` works; `gpt-5.2` does not. 6. **Check your balance.** A 402 means either your credits balance hit zero or there are no available tokens for the instrument. Open the dashboard at [app.thegrid.ai](https://app.thegrid.ai) and check both balances. 7. **Check the request body.** A 400 with no clear cause usually means a malformed request body. A missing required field, an invalid JSON structure, or a parameter we don't accept. Compare your body to the [Consumption API reference](/docs/api-reference/consumption-api.md). 8. **Check your token limits.** A 400 mentioning input or context length means your tool sent more tokens than the instrument's window. This is common with coding harnesses (OpenCode, Crush, Cline) that pack large file contexts and tool outputs. The harness decides how much to send from its configured limits, so set the maximum input tokens (120K for Standard and Prime, 922K for Max) and a maximum output below the context window. See [Best practices → Set the input and output token limits](/docs/integrations-and-best-practices/best-practices.md) for per-tool config keys. If you've walked through all of this and you're still stuck, send the request ID (returned in the `x-request-id` response header) to . Include the timestamp, the instrument, and what you expected vs. what you got. ## Status page [status.thegrid.ai](https://status.thegrid.ai) shows current uptime and any active incidents. Subscribe to incident alerts for production integrations. ## Where else to look * For redirect behavior and how request routing works: [API reference → Request routing and redirects](/docs/api-reference/request-routing-and-redirects.md). * For full error code semantics and rate limits: [API reference → Errors and rate limits](/docs/api-reference/errors-and-rate-limits.md). * For balance management and Auto-Reload setup: [Best practices](/docs/integrations-and-best-practices/best-practices.md) and [API reference → Auto-Reload](broken://pages/pdlcsdUZJSSSfhsYQcIu). * To start from authentication basics: [API reference → Authentication](/docs/api-reference/authentication.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://thegrid.ai/docs/integrations-and-best-practices/troubleshooting.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.