Stuck? Start here
Written by a person. Last read by a person on 2026-09-05, 3 days ago. Its facts were checked by the eval suite on 2026-09-07.
Something half worked and you cannot tell whether that is progress, an error arrived and you do not know what it rules out, or you are stuck and want to describe your situation to somebody who has seen it before.
Most documentation assumes you either succeeded or failed. Almost nobody is in either state. You are usually somewhere — something happened, part of it worked, and you cannot tell whether that is good news.
This page is for that. Find where you got to, and it will tell you what is already working.
Where did you get to?
Each of these is a position, not a verdict. Read the one that matches what you actually saw.
Anything at all came back, even an error
What this proves. Your network path, TLS and DNS are all working, and the API answered you. Everything that fails before this point fails silently and confusingly, so this is further than it feels.
The error names an HTTP status, like 401 or 429
What this proves. The API parsed your request well enough to reject it specifically. That is a much better position than a connection error, because now the failure tells you which family you are in.
Text began arriving, then stopped
What this proves. Auth, permissions, request shape and rate limits were all fine. You got past every check the API makes before generating. What remains is the transport.
The whole response arrived and stop_reason was end_turn
What this proves. The workflow works. Anything you change from here is tuning rather than fixing.
What your error already tells you
An error is evidence, not a verdict. Most failures prove that several hard things are already working, and nobody tells you which.
These come from data/error-families.yaml, rendered rather than retyped, so what you read here
cannot drift from what the classifier uses.
Authentication and permission
What this already proves is working. You reached the API and it answered. DNS, TLS, the network path and your request shape are all fine. What is left is one credential.
Check these before blaming the API. A bad key fails in a way that reads like a bug in your own code, so people go looking in the wrong file for an hour. Check which key the process actually loaded before you read a single line of the request.
Also in this family. A key that works locally and fails in CI, a key without access to the model you named, and an OAuth token sent in the wrong header.
Billing and spend limits
What this already proves is working. Everything technical is working. Your credentials are valid, your request parsed, and you reached the API. This is an account state, not a code problem, and no amount of debugging your request will move it.
Check these before blaming the API. This one is hard to place because it returns the same status codes as two other families. A spend limit you set returns 400, while your tier's monthly cap returns 429 with no retry-after header and keeps failing until the month rolls over.
Also in this family. A payment method that expired, and a workspace limit that is lower than the organization's.
Rate limiting
What this already proves is working. Your credentials are valid, your request shape parsed, and you reached the API. All three of those are confirmed, so throttling is a timing problem rather than a correctness one.
Check these before blaming the API. Check whether it is really your traffic. Limits are per organization, so another process, another environment, or a colleague's backfill spends the same budget.
Also in this family. Requests, input tokens and output tokens are limited separately; a sharp ramp can trip an acceleration limit even below the steady-state ceiling.
Malformed request
What this already proves is working. You are authenticated and you reached the API. The connection, the key and the permissions are all confirmed working. What is left is the shape of one request.
Check these before blaming the API. Usually a serialization problem rather than a misunderstanding of the API: an object that stringified oddly, a field that arrived as null, a document larger than it looked.
Also in this family. A first message that is not from the user, a parameter the target model has removed, and a request over the size limit.
Streaming state
What this already proves is working. The request was accepted and the model began responding, which means auth, permissions, request shape and rate limits all passed. Everything the API checks before generating is confirmed, and what remains is the transport between you and it.
Check these before blaming the API. A dropped connection is indistinguishable from a slow model at the client. Check proxies and idle-connection timeouts on the path before the API.
Also in this family. An error arriving mid-stream after a 200, a stream abandoned without being closed, and a long non-streaming request killed by an idle timeout.
Service capacity
What this already proves is working. Nothing you sent is wrong. Auth, shape, quota and connection are all confirmed good, because the API got far enough to tell you it is busy.
Check these before blaming the API. Nothing about your request caused this and nothing about your request fixes it. The signal is that it fails identically regardless of what you send.
Also in this family. Transient upstream errors and overload during broad demand spikes.
Environment and network
What this already proves is working. Nothing is confirmed yet, and that is useful to know: this failure happened before the API saw anything, so no conclusion about your key or your request is available from it. Do not debug the request.
Check these before blaming the API. The family that never reaches the API at all, and therefore never produces an API error to look up. DNS, a proxy, a firewall, a clock skewed enough to break TLS.
Also in this family. Connection resets, TLS failures, and a corporate proxy returning an HTML error page that the SDK cannot parse as JSON.
Still stuck? Bring us your situation
We cannot come to your environment, so the next best thing is for you to describe it.
Four questions:
- What are you trying to do? In your own words.
- What did you run or send?
- What came back? The exact message. The wording is the evidence.
- What did you expect instead?
Before you paste anything: remove keys, tokens, and paths containing your username. Nothing on this page needs them.
Why four fields rather than one box
A single free-text box cannot be checked field by field, cannot be mapped onto the taxonomy, and does not make you articulate the problem. That last one is not politeness. Saying what you expected to happen, separately from what did, is the step most often skipped and most often sufficient.