This guide uses source checks from Sep 26, 2026. Provider and gateway prices can change; preserve the checked date with every forecast.
Why This Topic Matters Now
The Sep 25 report kept DeepSeek API, Chinese AI API, and OpenAI-compatible search intent in the active market set. Many integrations still treat every non-200 response as the same problem: retry, switch models, or show a generic error. That shortcut can duplicate requests, hide billing gates, and make an upstream capacity event look like an application bug.
This runbook is for Tier 1 and Tier 2 teams using an OpenAI-compatible Chinese AI API from a SaaS backend, worker, or coding tool. It maps response classes to actions, preserves request and usage evidence, and uses AIWave's live route and dated pricing endpoints as separate evidence layers. The result is a bounded policy that an on-call engineer can execute without guessing.
Source Facts Checked Today
AIWave /api/pricing was checked from production on Sep 26, 2026 and returned HTTP 200, success=true, 73 live route rows, pricing_version a42d372ccf0b5dd13ecf71203521f9d2, auto_groups=['default'], group_ratio default=1 and vip=0.9, with the public OpenAI-compatible POST path /v1/chat/completions. The public /api/v1/pricing endpoint returned HTTP 200 with 56 dated USD rows, pricing_version 83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5, checked=2026-09-10, and updated_at=2026-09-18. Use the live response for route availability and the dated JSON for a forecast; they are not one interchangeable rate table.
The OpenAI error-code guide checked on Sep 26, 2026 groups failures into authentication, permission, rate-limit, server, and request problems. The DeepSeek error-code page checked on the same date provides provider-specific examples. Use both as references, but let the exact gateway response, request ID, and route contract decide the operational branch.
The live AIWave response checked on Sep 26, 2026 includes an OpenAI-compatible POST route and current rows such as deepseek-v4-pro, deepseek-v4-flash, glm-5, qwen3.5-plus, kimi-k3, step-3.5-flash, and MiniMax-M3. This is route metadata, not a guarantee that every capability is exposed for every model; validate the specific call shape before rollout.
The dated AIWave pricing JSON checked in this run lists deepseek-v4-pro at $1.914 input, $0.0637362 cache-hit input, and $5.742 output per 1M tokens, and glm-5 at $1.55 input, $0.40000075 cache-hit input, and $4.96 output, both effective 2026-08-27. These dated gateway rows support forecasting only; recheck live pricing before funding or scaling.
Planning Matrix
A source-dated planning matrix keeps the page useful for engineers and procurement reviewers. It turns a search query into an auditable route decision instead of a loose model preference.
| Class | Default action | Evidence to retain |
|---|---|---|
| 401/403 | Stop and inspect credential or permission | Status, request ID, redacted route |
| 402 | Stop billing loop and notify owner | Account group, balance state, usage |
| 429 | Back off within a bounded window | Retry-after, attempt count, queue age |
| 5xx | Retry only idempotent work | Upstream code, latency, final decision |
| Timeout | Classify before fallback | Deadline, partial state, attempt ID |
| Validation | Fix caller before retry | Payload schema and test fixture |
Implementation Pattern
The implementation pattern keeps credentials as placeholders, pins the AIWave base URL, records the model, and leaves room for route-specific controls. Production applications should move credentials into environment or secret storage.
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY_HERE",
base_url="https://aiwave.live/v1",
)
policy = {"model": "deepseek-v4-pro", "max_attempts": 2, "deadline_s": 20}
try:
result = client.chat.completions.create(
model=policy["model"],
messages=[{"role": "user", "content": "Return one bounded status check."}],
temperature=0.0,
max_tokens=180,
timeout=policy["deadline_s"],
)
print({"status": "ok", "finish": result.choices[0].finish_reason,
"usage": result.usage, "request_id": getattr(result, "id", None)})
except Exception as exc:
print({"status": "classified_failure", "type": type(exc).__name__,
"retry_budget_remaining": policy["max_attempts"] - 1})
Turn the Query Into a Contract
For an OpenAI-compatible error policy, define the request shape, model ID, data class, output ceiling, timeout, retry ceiling, owner, and source date before the first trial. A short contract gives engineering, security, and finance the same object to review when a provider changes a route or billing field.
Separate Live Routes From Dated Rates
The live AIWave pricing response answers which route rows and endpoint types are available at check time. The public pricing JSON is a dated USD snapshot for forecasting. Store both URLs, versions, checked dates, model IDs, and account-group context instead of presenting a volatile source as a permanent quote.
Use a Small Acceptance Set
A useful canary covers a normal request, a malformed request, a repeated prefix, a long output, a disconnect, and a deliberate stop condition. Record request ID, model ID, status, token usage, finish reason, retry count, and reviewer outcome. This turns a search result into evidence that can survive a route update.
Keep Data and Credentials Bounded
OpenAI-compatible clients reduce integration work, but they do not choose the right data boundary. Keep the credential server-side, use a visible placeholder in examples, redact fixtures, and attach a data-class decision to every route policy. Do not let a feature flag or model alias silently widen what crosses the API.
Make Recovery Observable
Retry only failures that are safe to retry and cap every fallback. Preserve the original request ID, mark the stop reason, and distinguish provider errors from client validation, policy rejection, and budget stops. Silent loops hide both reliability failures and billing variance.
Use AIWave's Evidence Layer
Use the Models docs, Chat Completions docs, live pricing API, dated Pricing JSON, Status, and Trust. Recheck the live route table before rollout, the dated pricing JSON before a budget review, the status page before a launch window, and the trust page before procurement. Keep each checked date visible in the record.
Release Gate
Promotion is ready when the provider source is dated, the AIWave route is rechecked, the acceptance set passes, the billing fields are understood, and a named owner can stop or reverse the change. If a field is unknown, label the work as a trial rather than production.