TL;DR — Bookmark page for the errors that happen between your code and the model: parameter renames, proxies that break streaming, vector stores that reject your embeddings, JSON that will not parse. These are integration-layer failures, which is why provider status pages are green while your feature is broken. Indexed by the exact string, because that is what you paste into a search box at 2am.
Parameters the model rejects
| Exact error | Meaning | Fix |
|---|---|---|
Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead. (HTTP 400, unsupported_parameter) |
Reasoning models cap reasoning + visible output together, so the parameter was renamed. A same-sized budget can now be eaten entirely by reasoning | Rename it, and normalise once |
temperature / top_p / penalties rejected on the same models |
Sampling is fixed on reasoning-family models — a migration surfaces as a sequence of 400s, not one | Same guide |
Streaming that dies mid-response
| Exact symptom | Meaning | Fix |
|---|---|---|
read ECONNRESET / Error: aborted during an SSE stream |
Almost always an intermediary, not the model: idle timeout counting silence between tokens, or a load-balancer response cap | Five causes, checked in order |
| Nothing for 30s, then everything at once | Response buffering — the data was never lost, it was held | Proxy config for SSE |
Stream ends with no finish_reason |
Truncated, not complete — do not show the partial answer as final | Client-side handling |
| 504 on long generations | Gateway timeout tuned for web requests, not LLM latency | Gateway timeout limits |
Embeddings & vector stores
| Exact error | Meaning | Fix |
|---|---|---|
expected 1536 dimensions, not 3072 / Vector dimension does not match the dimension of the index |
You changed embedding model; an index is coupled to the model that built it | Re-embed vs shortened dimensions |
| No error, but retrieval quality collapsed | Two models' vectors mixed in one collection — the silent version, and the expensive one | Why lengths matching is not compatibility |
Structured output
| Symptom | Meaning | Fix |
|---|---|---|
json.loads fails on prose or ```json fences |
Model wrapped the object in conversation — the case structured-output modes actually solve | Four JSON failures |
| JSON cut off mid-object | Token budget, not formatting. Check finish_reason |
Same guide |
| Valid JSON, wrong field names or types | JSON mode guarantees syntax, not structure — you want schema enforcement | Same guide |
| Valid, correctly shaped, and factually wrong | No output mode fixes this. Validate content against something real | Same guide |
Why these cluster at the integration layer
A pattern worth naming: every entry above is a contract mismatch between your stack and the provider — a parameter that got renamed, a proxy built for request/response meeting a stream, an index coupled to a model, a parser meeting prose. None of them show up on a provider status page, and none are fixed by retrying.
That is also the honest argument for putting a routing layer between your code and the providers: parameter normalisation, streaming behaviour, and model-family differences get handled in one place instead of in every service. Gateway vs router, and which you actually need.
Contribute an error
Hit something not listed? The bar for inclusion: the exact error string, the stack it appeared in, and a reproducible cause. This reference is only useful while it stays real — we do not list errors we have not seen.