01
First confirm that your workload fits the supported subset.
A migration is usually smallest when your application uses text chat completions, server-sent event streaming, function tools, or structured JSON and the client allows a custom base URL. Compatibility describes request and response shapes, not identical model behavior.
Inventory the exact endpoints and fields your production traffic sends. Hosted assistants, embeddings, image or audio inputs, and unrelated vendor features are not implied by chat-completions compatibility.
- Record the SDK and runtime versions you deploy.
- Capture representative requests after client-side serialization.
- List every status code, header, and stream event your application depends on.
- Separate schema compatibility tests from model-quality evaluations.
02
Change the base URL, API key, and public model alias.
Keep API keys on the server. Do not expose a BrokenGPT secret in browser JavaScript, mobile bundles, logs, analytics, or source control. Start with a non-streamed request so response and error handling are easy to inspect.
JAVASCRIPT MIGRATION
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.BROKENGPT_API_KEY,
baseURL: "https://brokengpt.com/v1",
});
const result = await client.chat.completions.create({
model: "broken-one",
messages: [{ role: "user", content: "Explain this plainly." }],
});
console.log(result.choices[0]?.message?.content);03
Run a migration matrix before shifting traffic.
| Surface | Verify | Failure to catch |
|---|---|---|
| Messages | Roles, Unicode, null assistant content, tool messages | Serialization or validation errors |
| Streaming | SSE chunks, disconnects, finish reason, [DONE] | Hung UI or duplicated text |
| Tools | Schema, tool choice, tool-call loop, argument parsing | Unsafe or malformed execution |
| JSON | Schema validation and non-streamed delivery | Invalid downstream objects |
| Limits | Context, request rate, key spend and token caps | Surprise 400 or 429 responses |
| Accounting | Input/output usage, credits, workspace attribution | Incorrect budgets or reporting |
04
Roll out with an observable fallback boundary.
- Route a small, non-critical workload to BrokenGPT and attach your own trace identifier.
- Compare correctness, refusal, latency, tool behavior, and cost on the same prompt set.
- Handle 400 errors without retry, 401 and 403 as credential problems, 429 with bounded backoff, and 5xx as temporary service failures.
- Increase traffic only after application metrics and human review meet your acceptance criteria.