Changing a model or Base URL is not a migration: streaming, tool calls, errors, limits, and usage may differ. Completion requires a provider shutdown date, every dependency, observed-contract comparison, and a reversible cutover. On August 25, 2026, OpenAI publishes shutdown dates and replacements in Deprecations; its general policy is six months for generally available models, three for specialized variants, and potentially less for preview. Schedule from the specific entry, not an assumption.
1. Record the event
Before code changes, record the official source, check date, old and replacement endpoint/model, shutdown_date, and owner. Take that date only from the provider notice; otherwise write unknown, assign a recheck owner, and do not invent urgency.
deprecation_source: https://developers.openai.com/api/docs/deprecations
checked_at: 2026-08-25
old_endpoint: /v1/chat/completions
old_model: OLD_MODEL_ID
replacement_endpoint: /v1/chat/completions
replacement_model: NEW_MODEL_ID
shutdown_date: YYYY-MM-DD
owner: team-name
2. Inventory dependencies
Record endpoint, Base URL, protocol, model ID/fallback, payload and messages, tool schema/required fields/choice mode, SSE parser/usage, errors/retry policy, prompt version, and all services, cron, workflows, SDKs, CI variables, serverless jobs, n8n/Dify workflows, secret-store entries, and background jobs. Keep secret names and owners, never values.
3. Build control requests
Use sanitized real tasks: factual text, required-field JSON, a valid tool call, a no-tool case, completed streaming, negative 4xx, and a transient error or test double. Compare the contract, not wording: schema, tool name/arguments, application result, required facts, stream completion, and retry. Measure cost and latency separately on your own run.
4. Test streaming and errors separately
Record event type and data format, completion signal, usage location, disconnects before the first token and after partial output, and whether retry can duplicate an external action. Keep HTTP status, machine-readable code, and retry boundary. Never retry 401, 403, or schema validation errors automatically; for 429 and temporary 5xx, honor Retry-After, cap attempts, and add idempotency for side effects.
5. Dual-run both paths
In test, keep the old path as baseline and send the same fixtures to the new path. Save:
case_id | old_result | new_result | contract_pass | difference | decision
Different wording can pass; changed tool arguments, missing fields, stream termination, or new errors need a client fix or explicit acceptance.
For BetterToken transport use https://www.bettertoken.ai/v1/chat/completions, the user's Bearer Key, and a current Model ID from Model Plaza or Setup. Create a test Key, execute the control request against the current Chat Completions contract, and record the HTTP status and a verifiable response field; this checks request format, not model equivalence.
Before cutover, compare the control-request fields with the current contract. Open the Chat Completions guide
6. Cut over reversibly
Have a feature flag or versioned provider config, owner and observation window, error/contract-test/business-invariant metrics, exact rollback condition, and old config without secrets. Deploy both contracts, enable controlled traffic, compare, expand only when criteria pass, roll back on a written invariant failure, and remove the old path only after observation and before shutdown. Leave time to fix, rerun, and cut over again: rollback cannot restore a shut-down API.
Readiness evidence
Require the official link/date, owned dependency inventory, versioned fixtures and dual-run results, a signed decision for every material difference, and a measurable cutover/rollback runbook. Without one, remain migration_in_progress even after a 200.
Sources checked August 25, 2026: https://developers.openai.com/api/docs/deprecations and https://docs.bettertoken.ai/api-reference/chat-completions.
Originally published on the BetterToken blog.
BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.
Top comments (0)