Source pack

This is an in-place refresh of the existing CometAPI fallback runbook URL. The slug is preserved exactly, and this draft does not create a new URL.

Source coverage status: pending_review. Exact endpoint paths, auth header formats, model identifiers, rate limits, and billing details must be verified from the linked CometAPI documentation before this runbook is treated as production-final.

Intent brief

• Audience: SREs, platform engineers, backend engineers, and AI application owners who route chat completion requests through CometAPI and need controlled failover behavior.
• User intent: Learn how to design a practical fallback runbook for CometAPI chat completions without assuming undocumented endpoint, auth, rate-limit, model, or billing details.
• Operational job: Decide when to retry, when to fail over to a validated fallback model or provider path, when not to fail over, and what to log so incidents can be reconstructed.
• Out of scope: Current pricing, provider rankings, benchmark claims, exact model availability, or guaranteed uptime claims. Verify those directly in current CometAPI materials and account configuration.

CometAPI chat completions fallback runbook

Last reviewed: 2026-06-06.

Who this is for: This runbook is for operators responsible for chat completion reliability when CometAPI is part of the production request path.

A fallback runbook should not be a blind “try another model” rule. For chat completions, failover changes latency, cost exposure, answer style, safety behavior, and sometimes the contract your downstream code expects. Treat the CometAPI text chat API documentation as the source of truth for the request and response contract, and use the CometAPI documentation home to verify the current API entry points before any production test.

Key takeaways

• Build fallback around classified signals, not a single catch-all exception handler.
• Do not fail over invalid client requests, bad authentication, schema mistakes, or other defects that another model path will not fix.
• Keep primary and fallback paths contract-compatible: prompt format, response parsing, streaming policy, tool use, schema requirements, and token budget must be validated.
• Record every attempt under one trace so the system stores one final selected answer and can explain why earlier attempts were abandoned.
• Verify endpoint paths, auth headers, request fields, response fields, error behavior, rate-limit behavior, and billing assumptions from CometAPI sources before enabling automated fallback.

Concise definition

A chat completions fallback runbook is an operator-approved sequence for detecting request-path degradation, classifying the failure, deciding whether fallback is allowed, calling a pre-validated alternate path, validating the returned answer, and recording the final outcome.

For CometAPI, the runbook should begin with contract verification against the CometAPI text chat API documentation, then move into client-side reliability controls such as timeouts, retry budgets, circuit breakers, and alert routing.

Contract details to verify

Do not copy these values from memory or from another provider’s examples. Verify each item against the linked CometAPI source before rollout.

Monitoring signals that should drive fallback

Use this table as a starting classifier. The action column is intentionally conservative: fallback should protect users from transient degradation, not hide client bugs.

Runbook sequence

1. Verify the CometAPI contract before coding fallback

Before enabling fallback logic, confirm the live contract from the CometAPI text chat API documentation:

• base URL and chat endpoint path;
• authentication header format;
• required request fields;
• optional request fields your app uses;
• response body paths your parser depends on;
• error-body shape and status semantics;
• streaming behavior, if your application streams;
• usage, rate-limit, and billing signals, if exposed.

Store these verified values in configuration, not scattered through business logic.

2. Define primary and fallback compatibility

A fallback candidate is not valid just because it can answer text. It must satisfy the same operational contract:

• accepts the same prompt structure or has a tested prompt adapter;
• supports your required response format;
• fits your token budget;
• meets your latency objective under load;
• is approved for the same data-handling and safety requirements;
• produces output your downstream parser can consume.

If any of those are unknown, mark the fallback candidate as not production eligible until validated.

3. Classify the first failure

On every failed or degraded primary attempt, classify the signal before taking action:

1. Retryable transient: timeout, temporary server-side failure, or route unavailability.
2. Capacity or quota pressure: rate-limit-like behavior that may or may not be safe to route around.
3. Client defect: invalid request, bad payload shape, unsupported field, or parser mismatch.
4. Auth or account defect: invalid key, missing permission, account state, or policy block.
5. Output defect: response arrived but fails your contract validation.

Only the first, selected second, and selected fifth categories should normally reach fallback. Client defects and auth/account defects should go to owner action, not another model call.

4. Apply a bounded retry and fallback budget

Use a request-level budget that limits total time, total attempts, and duplicate generation risk. Example values must be tuned to your service objective and cost profile; they are not universal facts.

A conservative policy might be:

• one primary attempt;
• one retry only for clearly transient errors;
• one fallback attempt only after the request remains within the user-facing deadline;
• no fallback for non-idempotent tool calls or side effects unless the tool layer has its own idempotency controls.

The important rule is that the budget applies to the whole user request, not separately to each model path.

5. Execute a documented canary call

Use a sanitized canary that confirms your configured endpoint, auth header, request body, and parser. Replace all placeholders with values verified from the current CometAPI documentation. Do not paste production secrets into terminals or incident tickets.

TRACE_ID="<TRACE_ID_FROM_YOUR_OBSERVABILITY_SYSTEM>"

curl --request POST \
  --url "<COMETAPI_BASE_URL_FROM_DOCS><COMETAPI_CHAT_PATH_FROM_DOCS>" \
  --header "<AUTH_HEADER_FROM_DOCS>" \
  --header "Content-Type: application/json" \
  --max-time "<CLIENT_TIMEOUT_SECONDS_TO_TUNE>" \
  --data-binary @- <<JSON
{
  "<MODEL_FIELD_FROM_DOCS>": "<VALIDATED_MODEL_ID>",
  "<MESSAGES_FIELD_FROM_DOCS>": [
    {
      "<ROLE_FIELD_FROM_DOCS>": "<SYSTEM_OR_DEVELOPER_ROLE_VALUE_FROM_DOCS>",
      "<CONTENT_FIELD_FROM_DOCS>": "Return one sentence confirming the fallback canary path for trace ${TRACE_ID}."
    },
    {
      "<ROLE_FIELD_FROM_DOCS>": "<USER_ROLE_VALUE_FROM_DOCS>",
      "<CONTENT_FIELD_FROM_DOCS>": "Canary request. Do not include secrets."
    }
  ]
}
JSON

Before using this in automation, confirm the request field names, role values, and endpoint values from the CometAPI text chat API documentation.

6. Validate the fallback response before returning it

A fallback answer should pass the same output checks as the primary answer:

• response parsed successfully;
• required content field exists;
• finish or stop condition is acceptable;
• structured output validates, if required;
• safety or policy checks pass;
• answer is not an empty placeholder;
• trace metadata links the final answer to all attempts.

If the fallback response fails validation, return a controlled application-level failure instead of silently presenting an unreliable answer.

7. Persist one final outcome

For each user request, store one final outcome and the full attempt chain:

• request trace ID;
• primary model/path identifier used by your configuration;
• fallback model/path identifier used by your configuration;
• status and latency for each attempt;
• error class and sanitized error body;
• final selected response source;
• whether a retry or fallback consumed extra budget;
• operator-facing reason code.

This makes incident review possible without exposing prompts or secrets unnecessarily.

Practical validation steps before enabling fallback

Run these tests in staging or a controlled canary environment before production rollout.

1. Contract check: Compare your configured base URL, chat path, auth header, request fields, and parser paths against the current CometAPI docs.
2. Primary success canary: Send a minimal chat completion request through the primary path and validate the response parser.
3. Fallback success canary: Send the same safe canary through the fallback path and compare parser compatibility.
4. Timeout injection: Force the primary request to exceed your client timeout and confirm the fallback budget behaves as expected.
5. Server-error simulation: Stub or simulate a server-side failure and confirm only eligible errors trigger fallback.
6. Auth failure simulation: Use a deliberately invalid credential in a non-production environment and confirm fallback does not run.
7. Invalid request simulation: Send a malformed request in a safe test and confirm the client reports a contract failure instead of failing over.
8. Rate-limit drill: If your account and docs expose rate-limit behavior, verify alerting and fallback rules without assuming undocumented header names.
9. Streaming drill: If streaming is enabled, test failures before the first token and after partial output. Define which cases are allowed to fallback.
10. Cost and usage review: Reconcile attempt counts against usage or billing records available to your account. If details are unclear, use the CometAPI support help center to confirm.

Decision rules to encode

Use explicit reason codes instead of opaque exception strings.

Thresholds such as “two failures” or “three minutes” should be treated as examples to tune against your traffic, SLO, and cost tolerance. They are not CometAPI contract values unless current documentation explicitly says so.

Alerting and escalation

Create separate alerts for:

• sustained primary-path failure rate;
• fallback-path failure rate;
• fallback volume above normal baseline;
• auth or account errors;
• parser or schema failures;
• latency SLO breach;
• usage or spend anomaly after retries/fallback;
• streaming interruption rate, if streaming is used.

Escalate documentation or account questions through the CometAPI support help center. Use the existing refreshed page URL as the historical operator note, but use the current CometAPI docs for live contract decisions.

Related operational resources

• LLM API reliability overview
• All LLM API reliability posts

FAQ

Should every chat completion error trigger fallback?

No. Fallback is appropriate for selected transient, capacity, route, or output-validation failures. It is usually wrong for invalid requests, broken auth, unsupported fields, or account-level problems.

Should I retry before falling back?

Often, yes, but only within a bounded request budget. A retry can clear a short transient issue; fallback can protect users when the primary path remains unhealthy. Both can increase latency and usage, so record them separately.

Can I fallback after a streaming response has started?

Be careful. Once the user has seen partial output, a fallback answer may duplicate or contradict the visible stream. Define a policy for pre-first-token failure, mid-stream interruption, and post-stream parser failure.

Can I hard-code the CometAPI chat endpoint from an old example?

No. Verify the current base URL and chat path from the CometAPI text chat API documentation before deploying. This refresh intentionally avoids hard-coding endpoint paths that were not quoted in the provided source pack.

What should I log for each fallback event?

Log a trace ID, attempt number, configured model/path identifier, status class, latency, sanitized error body, fallback reason code, final selected response source, and whether the request consumed retry or fallback budget. Do not log secrets or sensitive prompt content unless your data policy allows it.

How do I confirm billing or rate-limit assumptions?

Do not infer them from generic API behavior. Check your account materials, current CometAPI documentation, and the CometAPI support help center for the specific behavior that applies to your usage.

Sources checked

If CometAPI is part of your production routing plan, validate the contract against the sources above, run the canary sequence, and only then enable automated fallback. Start with CometAPI when you are ready to evaluate the platform against your own reliability requirements.