01 / Inventory
Check the request, not just the endpoint.
Start with one representative production-shaped request and inventory the operations and fields it uses. OpenWaya currently supports model listing, text and image-URL Chat Completions, text Responses, float embeddings, JSON object mode, and streaming. Validate each requested model and capability through the OpenWaya catalog before moving traffic.
- Remove or redesign tool calls, JSON Schema output, logprobs, reasoning-effort controls, stored Responses, and base64 embedding output before cutover.
- Do not assume an OpenAI model ID is published; select its visible OpenWaya catalog ID or openwaya/auto.
- Keep prompts, outputs, and API keys out of migration logs and support messages.
02 / Client
Replace the credential and base URL.
Create a scoped OpenWaya key, keep it in your server-side secret store, and set the client base URL. The official JavaScript and Python OpenAI SDK paths are covered by compatibility tests for listing models, Chat Completions, Responses, embeddings, and both streaming formats.
const client = new OpenAI({
apiKey: process.env.OPENWAYA_API_KEY,
baseURL: "https://api.openwaya.africa/v1",
maxRetries: 0,
timeout: 30_000,
});
const result = await client.chat.completions.create(
{
model: "openwaya/auto",
messages: [{ role: "user", content: "Hello from Africa" }],
},
{ headers: { "Idempotency-Key": crypto.randomUUID() } },
);03 / Response
Keep compatibility and add evidence.
OpenWaya returns the familiar operation shape plus OpenWaya route evidence. Preserve your normal content parser, then record the response request ID, resolved model, provider, route-attempt count, and normalized usage as content-free operational metadata.
- For Chat Completions streams, request stream_options.include_usage when terminal usage is required.
- For Responses streams, consume typed response.* events rather than Chat Completion chunks.
- Use the stable OpenWaya error code and request ID for retry and support decisions.
const routed = result as typeof result & {
openwaya: { provider: string; route_attempt_count: number };
};
console.log({
requestId: routed.id,
model: routed.model,
provider: routed.openwaya.provider,
attempts: routed.openwaya.route_attempt_count,
usage: routed.usage,
});04 / Cutover
Move traffic in measured steps.
Run the same fixture against both providers, compare semantic output handling rather than exact generated text, and reconcile request counts and spend. Move a bounded percentage of eligible traffic, observe errors, latency, route attempts, usage, and balance, then expand. Keep the old client available until the observation window closes.
- Reuse an idempotency key only for retries of the identical request.
- Set explicit client deadlines and bounded retry behavior; do not stack SDK retries on OpenWaya fallback blindly.
- Rollback means switching new requests to the previous client, not replaying completed billable work.