# Troubleshooting

Source: https://docs.getworg.com/troubleshooting

Find the symptom, run the check. Your coding agent gets the same table in /agent-context.md.

## First checks

1. List the models with your key: curl https://api.getworg.com/v1/models -H "Authorization: Bearer $WORG_API_KEY". A list back means the key and base URL are right.
2. Read the code field of the error, not only the message. The message can change; the code does not.
3. Keep the x-request-id header from the response. Send it with any question to team@getworg.com.

## Symptoms

| Symptom | Check | More |
| --- | --- | --- |
| 5xx errors or timeouts | Check the status page first: https://status.getworg.com. If it shows an incident, the fault is on the Worg side and your code can stay as it is; retry with backoff until it clears. If everything is up, send the x-request-id to team@getworg.com. | [Status page](https://status.getworg.com) |
| 401 invalid_api_key | The key is missing, wrong, or has quotes or spaces around it. Check that WORG_API_KEY is set in the process that sends the request, and that the header is Authorization: Bearer <key>. | [Authentication](https://docs.getworg.com/authentication#send-the-key) |
| 404 not_found on every request | The base URL is wrong. It must be exactly https://api.getworg.com/v1: with /v1, and without /chat/completions at the end. Clients add the path themselves. | [Connect clients](https://docs.getworg.com/connect-clients#settings) |
| 404 not_found on /v1/responses, /v1/messages or /v1/embeddings | The client calls an API that Worg does not offer. Switch it to Chat Completions. In the Vercel AI SDK, use the OpenAI-compatible provider or openai.chat(), not openai(). | [Connect clients](https://docs.getworg.com/connect-clients#not-supported) |
| 404 model_not_found | The model ID is mistyped or has a prefix the client did not remove. Copy an ID from GET /v1/models, or use combo/<name> for a combo. | [Models and compatibility](https://docs.getworg.com/models) |
| 402 insufficient_balance while the balance still shows money | Worg holds the most a request can cost before sending it. Without max_tokens the hold covers the whole output limit, which can be more than the balance. Set max_tokens; the error message states both amounts. | [Rate limits](https://docs.getworg.com/rate-limits#hold) |
| 402 key_budget_exceeded, workspace_budget_exceeded or org_budget_exceeded | A monthly budget is used up. A top-up does not help: an admin raises the budget in the console, or you use another key. | [Errors and retries](https://docs.getworg.com/errors#key_budget_exceeded) |
| 403 model_not_allowed | The key is limited to other models. An admin adds the model to the key, or you use a key that allows it. | [Authentication](https://docs.getworg.com/authentication#keys) |
| 403 key_suspended | The key spent far more than usual in the last hour. An owner or admin rotates or resumes it in API keys. | [Authentication](https://docs.getworg.com/authentication#suspended-keys) |
| 429 rpm_exceeded, tpm_exceeded or concurrency_exceeded | Your own limits. They apply per key and to the whole organization, so a second key does not add capacity. Wait for the seconds in Retry-After and run fewer requests at once; coding agents that start parallel tasks reach the concurrency limit first. To go higher, write to team@getworg.com. | [Rate limits](https://docs.getworg.com/rate-limits#limits) |
| 429 capacity_busy or 502 upstream_unavailable | The lane is busy or briefly down. Retry with backoff. Call the model by its name alone, such as deepseek-v4.1-flash, to let Worg try its other lane in the same request, or use a combo. | [Models and compatibility](https://docs.getworg.com/models#model-without-a-lane) |
| A stream stops with an error chunk | The lane failed after the stream started. A started stream stays on its lane, even in a combo, so send the request again. | [Errors and retries](https://docs.getworg.com/errors#codes) |
| The answer is cut off (finish_reason "length"), or content is empty and reasoning_content is not | max_tokens ran out. On lanes that reason, the thinking uses output tokens too. Raise max_tokens or lower reasoning_effort. | [Models and compatibility](https://docs.getworg.com/models) |
| A CORS error in the browser | Browsers on other sites cannot call /v1. Call the API from your server and keep the key there. | [Authentication](https://docs.getworg.com/authentication#keep-keys-on-the-server) |

Every error code with its meaning is in [Errors and retries](https://docs.getworg.com/errors).

Next: [Errors and retries](https://docs.getworg.com/errors) · [Connect clients](https://docs.getworg.com/connect-clients) · [Agent context](https://docs.getworg.com/ai-agents)