Troubleshooting

Common errors when integrating with The Grid and how to fix them. Auth, base URLs, instrument strings, balance, and the "is it me or The Grid" diagnostic flow.

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. 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 Top Up 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: 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.
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 Top Up 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 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. 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.

   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. 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 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.

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 [e-mail]. Include the timestamp, the instrument, and what you expected vs. what you got.

Status page

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.

• For full error code semantics and rate limits: API reference → Errors and rate limits.

• For balance management and Auto-Reload setup: Best practices and API reference → Auto-Reload.

• To start from authentication basics: API reference → Authentication.