Last reviewed: 2026-07-15T02:49:26Z
Direct answer
When a CometAPI-backed feature slows down, fails, or changes to a fallback path, the user-facing message should explain the user impact, offer one safe next action, and avoid claims the product has not verified. Keep endpoint, authentication, model, pricing, quota, and support details tied to public documentation instead of putting speculative vendor details in the interface.
A useful degradation message has a stable contract: status, impact, next action, support path, and a traceable internal message key. For example: “This feature is taking longer than expected. You can retry, continue with a simpler result, or contact support with the reference shown here.” That kind of wording keeps the user oriented without exposing raw errors, stack traces, internal routing details, or unverified root-cause language.
If your team is setting up the CometAPI side of the flow, use Start with CometAPI and keep the visible copy separate from the integration notes.
Who this is for
This guide is for product engineers, support engineers, and technical writers who own the product experience around LLM-powered features. It fits teams that already have a CometAPI-backed chat, response, summarization, extraction, or assistant workflow and need a repeatable way to communicate temporary degradation.
Use it alongside reliability runbooks such as CometAPI chat reliability contract review and response-shape checks such as Check CometAPI Response Shape Before Promoting Fallback Traffic . The goal is not to make the message longer. The goal is to make the message safer, more consistent, and easier to support after the user reports a problem.
Key takeaways
- Lead with what changed for the user, not with provider or routing details.
- Give one safe recovery action before offering a support path.
- Use stable message keys so support and engineering can connect reports to logs.
- Keep endpoint and request-shape claims tied to the CometAPI chat and responses documentation.
- Do not name a model, price, quota, uptime target, billing outcome, or root cause unless your product has verified that exact detail.
- Treat retries as a product decision: show a retry only when repeating the action is safe for that workflow.
Operator workflow
Setup assumptions: the feature already has a CometAPI-backed request path, a controlled fallback path, a message catalog, and a non-secret way to label test runs. A local or staging credential placeholder may be documented as <API_KEY_PLACEHOLDER>, but real credentials should stay outside UI examples and support notes. The product should also have a support route that can receive a message key, timestamp, feature name, and request reference.
Happy-path request plan: send one short request through the same path the feature normally uses. For a chat-style interface, confirm that the request path and response handling match the documented chat completion contract. For a workflow built around a responses interface, confirm that the response handling is aligned with the documented responses contract. Then confirm that the UI shows the normal success state, hides fallback wording, and logs the message key as none or another explicit success marker.
Error-path check: repeat the same workflow with a missing credential placeholder, a malformed request body, or a controlled upstream failure in a safe non-production environment. The product should show a calm degradation message, a visible recovery option when retry is safe, and a support path when recovery is not immediate. The UI should not show the raw provider error, request payload, stack trace, secret name, billing interpretation, or model-specific assumption.
Minimum assertions: the user sees exactly one primary status message; the message describes impact in plain language; the next action is possible from the current screen; the support path includes a reference the team can use; logs contain a stable message key; and the fallback state does not claim a specific model, price, quota, latency, uptime, billing result, or provider root cause.
Pass/fail logging fields:
timestamp: <ISO8601>
feature: <feature_name>
request_family: <chat | responses | other>
request_reference: <request_reference>
outcome: <success | degraded | failed>
message_key: <message_key>
fallback_used: <yes | no>
retry_shown: <yes | no>
support_link_shown: <yes | no>
operator_note: <short_safe_note>
What not to assert: do not assert a specific model name, an exact latency, a billing outcome, an account quota, a provider root cause, a guaranteed retry result, or a support response time. Those details can change or may require account-specific evidence. Keep them out of the user-facing copy unless your own product has verified them for that user and that request.
Message patterns
Use short, steady messages that match the user state. For a temporary slowdown: “This feature is taking longer than expected. You can retry now or continue with a simpler result.” For a fallback result: “We used a simpler response path for this result. Review it before using it in a final workflow.” For a blocked action: “We could not complete this request right now. Try again later or contact support with this reference.” For support handoff: “Include this reference when contacting support so we can find the request faster.”
The wording should not say that CometAPI is down, that a provider caused the issue, or that a particular model failed unless that is already confirmed by the product’s own evidence. The copy should also avoid blaming the user for ambiguous failures. If authentication is missing, the product can say the connection needs attention, but it should not display secret names or raw authorization strings.
Sources checked
- CometAPI documentation - accessed 2026-07-15; purpose: verify current CometAPI documentation navigation.
- CometAPI chat completions reference - accessed 2026-07-15; purpose: verify chat completion contract areas.
- CometAPI responses reference - accessed 2026-07-15; purpose: verify responses endpoint contract areas.
- CometAPI help center - accessed 2026-07-15; purpose: verify support and escalation documentation areas.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Client setup | The app uses the documented base URL and API-key pattern for its CometAPI client. | https://apidoc.cometapi.com/ | 2026-07-15 | “Configure the client using the documented CometAPI setup pattern.” |
| Chat request path | The feature’s chat request path, request body, and handled error cases match the documented chat completion areas. | https://apidoc.cometapi.com/api/text/chat | 2026-07-15 | “Send the request through the documented chat path and show a calm fallback if it fails.” |
| Responses path | The feature’s responses workflow handles non-success outcomes without assuming a model-specific result. | https://apidoc.cometapi.com/api/text/responses | 2026-07-15 | “Use the documented responses path when the feature is built around that interface.” |
| Support wording | Users have a clear help path when retry or fallback is not enough. | https://apidoc.cometapi.com/support/help-center | 2026-07-15 | “Point users to support with a request reference when recovery is not immediate.” |
Failure modes
Evidence gap: the product message names a model, price, quota, provider, or root cause that the team has not verified for the specific request. The safer action is to remove the claim and keep the message focused on user impact.
Raw error leak: the UI displays internal diagnostics, stack traces, request payloads, or authorization details. Replace the raw output with a message key and a short support reference.
Retry harm: the interface offers a retry for a workflow where repeating the action could duplicate work, spend budget, or create conflicting records. In that case, offer review, save, support, or a manual continuation path instead.
Fallback confusion: the product silently switches to a simpler result and presents it as equivalent. Tell the user when a simpler result path was used, and advise review before relying on it.
Support dead end: the copy tells the user to contact support but gives no reference. Include a safe request reference or message key so support can connect the report to logs.
Reader next step
Pick one CometAPI-backed feature and write three message variants: temporary slowdown, fallback result, and blocked request. Then run the workflow above against the happy path and one controlled error path. Keep the copy short, keep the evidence fields structured, and link the support message to a reference that does not expose secrets. For related operational fields, compare your log template with Log Fields That Make CometAPI Retries Reviewable .
FAQ
Should the message mention the exact failure?
Only when the exact failure class is known, safe to show, and useful to the user. Otherwise, describe the impact and the next action.
Should the copy name CometAPI?
It can when the product context already makes CometAPI relevant, such as setup or support documentation. In the product UI, the user usually needs the recovery action more than the vendor name.
Should every failure show a retry button?
No. Show retry only when repeating the action is safe. For workflows that create records, spend budget, or send messages, use review, save, support, or manual continuation instead.
Should the message name the model?
No. Keep the visible message model-neutral unless your own product has verified the model for that request and the detail helps the user recover.
What should support receive?
Support should receive a timestamp, feature name, request reference, message key, outcome, fallback-used flag, retry-shown flag, and a short safe note. Do not include credentials, full prompts, raw responses, or private payloads.