Classify CometAPI Partial Success Before You Retry

Last reviewed: 2026-07-21

Direct answer

Classify a CometAPI result before retrying by asking two separate questions: did the request reach a documented terminal state, and did the returned object satisfy the contract your application needs? Do not treat an HTTP status alone as the complete answer. A successful status with a missing, incomplete, or unexpected output may be unusable, while a documented error response can provide enough evidence to stop blind retries and choose a more specific action.

Use a small classification vocabulary that is consistent across your gateway:

• usable_success: the request returned the expected endpoint-specific object, the required output is present, and the application can safely commit the result.
• documented_error: the request returned a recognizable error envelope or terminal failure that can be recorded and handled without guessing.
• incomplete_result: the endpoint returned a recognizable object, but its status or required content indicates that the intended work is not complete.
• malformed_success: the transport and HTTP layers appear successful, but the object does not satisfy the minimum response contract expected by the caller.
• transport_failure: no usable HTTP response was available because the connection, timeout, or client transport failed.
• unknown_outcome: available evidence cannot show whether the remote operation completed, so an immediate replay could duplicate work or obscure the first attempt.

The key operational rule is simple: retry only when the classification and your application policy both permit it. A classifier does not prove that retrying is harmless. It creates a reviewable boundary where the caller can consider endpoint family, side effects, request identity, retry count, and evidence from the original attempt.

CometAPI documents separate contracts for Chat Completions and Responses. The Chat Completions reference identifies a successful non-streaming object as chat.completion and documents error envelopes. The Responses reference uses a response object with its own status and output structure. Your classifier can reuse common top-level labels, but it should validate each endpoint family against its own expected fields.

For broader response-shape preparation, read Check CometAPI Response Shape Before Promoting Fallback Traffic . For controls after a retry is approved, use Cap CometAPI Fallback Attempts per User Action .

Who this is for

This guide is for gateway owners, application engineers, and on-call responders operating CometAPI-backed features. It is most useful when a client sometimes receives an answer that looks successful at one layer but remains ambiguous at the application layer.

The workflow assumes you already know which endpoint family your route calls, have an approved model configuration maintained outside this guide, can capture sanitized request metadata, and can prevent concurrent retry workers from replaying the same user action. It does not assume that every failure is transient or that every successful HTTP response contains usable output.

Key takeaways

• Validate the endpoint-specific response contract before marking an attempt complete.
• Keep documented errors distinct from transport failures and unknown outcomes.
• Do not convert ambiguity into an automatic retry; require an explicit policy decision.
• Preserve the first attempt’s classification, request metadata, and retry count before sending another call.
• Use bounded classifications that operators can compare across incidents.
• Do not store credentials, full prompts, full outputs, or sensitive user data in classifier logs.
• Keep Chat Completions and Responses validation separate even when they share top-level decision labels.

A concrete classification workflow

1. Establish setup assumptions

Run the check through a non-production account, isolated test route, or other environment where a duplicate attempt cannot affect a real user workflow. Use a synthetic input and load <API_KEY_PLACEHOLDER> through your normal secret-management boundary. Select the endpoint family and model from your own approved configuration rather than copying an identifier from an article or old incident note.

Before the request, create an internal attempt identifier and associate it with one user action. Record the endpoint family, whether streaming is enabled, the permitted retry count, and whether the operation has any downstream side effect. The attempt identifier should be generated by your application; do not invent a provider request identifier before one is returned.

2. Execute the happy path once

Send one request using the documented Chat Completions or Responses contract. Capture the HTTP status, observed top-level object type, endpoint-specific status when present, presence of the required output field, returned request identifier when available, and client-side elapsed time. Do not log the credential, complete prompt, or complete response.

For Chat Completions, verify the non-streaming response against the fields your caller actually consumes. For Responses, inspect the response status and output structure expected by your integration. If streaming is enabled, do not classify the attempt from the first event or content fragment. Wait for the terminal event required by your client contract, or classify the interrupted stream separately from a completed non-streaming object.

A happy-path test passes when the object is recognizable, the required application output is present, the terminal state is acceptable, and the caller records usable_success without creating a second attempt.

3. Exercise one controlled error path

In the same isolated environment, send an intentionally incomplete request that is expected to produce a documented error. The purpose is to verify that your client captures the error envelope and assigns documented_error instead of collapsing every non-success into transport_failure.

Do not use invalid credentials for a routine classifier test unless credential handling is the specific behavior under review. Credential failures can trigger unrelated security controls and do not prove that response-shape classification works.

4. Apply minimum assertions

At minimum, assert that every completed client attempt has:

1. One endpoint family.
2. One classification from the approved vocabulary.
3. One retry decision: stop, retry_once, or escalate.
4. A reason for that retry decision.
5. A retry count tied to the originating user action.
6. Sanitized evidence showing which contract check passed or failed.
7. No second attempt when the first result is usable_success.

If the available data cannot distinguish an incomplete result from a completed result, use unknown_outcome. That label should route to a conservative decision rather than being treated as a synonym for transient failure.

5. Separate classification from retry policy

The classifier describes what was observed. The retry policy decides what to do. Keeping these functions separate prevents a low-level parser from silently replaying requests whenever it sees an unfamiliar object.

For example, transport_failure may permit one retry for a read-only request under a bounded policy, but unknown_outcome may require reconciliation or escalation first. A documented_error may require correcting the request, checking account configuration, or stopping immediately. A malformed_success may indicate contract drift and should retain the original evidence for investigation.

The policy should also enforce a per-action retry cap. See Retry Storm Guardrails for CometAPI Gateway Calls for the surrounding containment controls.

6. Record pass or fail without sensitive content

Use a compact record such as:

{
  "timestamp": "<ISO_TIMESTAMP>",
  "attempt_id": "<INTERNAL_ATTEMPT_ID>",
  "user_action_id": "<INTERNAL_ACTION_ID>",
  "endpoint_family": "<chat_completions_or_responses>",
  "streaming": "<true_or_false>",
  "http_status": "<STATUS_OR_TRANSPORT_FAILURE>",
  "response_object_type": "<OBSERVED_TYPE_OR_EMPTY>",
  "endpoint_status": "<OBSERVED_STATUS_OR_NOT_APPLICABLE>",
  "required_output_present": "<true_or_false_or_unknown>",
  "error_type": "<SANITIZED_ERROR_TYPE_OR_EMPTY>",
  "request_id": "<REQUEST_ID_PLACEHOLDER_OR_EMPTY>",
  "classification": "<APPROVED_CLASSIFICATION>",
  "retry_decision": "<stop_or_retry_once_or_escalate>",
  "retry_reason": "<SANITIZED_REASON>",
  "retry_count": "<INTEGER>",
  "result": "<pass_or_fail>"
}

A pass means the classifier produced one defensible label, the retry decision followed your policy, and the record contains enough sanitized evidence for review. A fail means the attempt lacked a classification, used contradictory labels, lost the original evidence, exceeded the retry cap, or sent another request after a usable result.

What not to assert

This workflow does not establish current model availability, pricing, rate limits, billing treatment, latency objectives, uptime, or universal retry safety. It also does not prove that an operation without a visible response had no effect. Verify those areas through the current documentation, your account configuration, and your own application evidence.

Failure modes

Treating every HTTP success as usable

A successful HTTP status is necessary for many happy paths, but the application still needs the expected object and required output. Marking the operation complete too early can pass malformed data to downstream code.

Retrying every documented error

A structured error is useful evidence. It may point to a request problem, authorization issue, unsupported configuration, or another condition that another identical request will not repair. Preserve the error classification before deciding what action is appropriate.

Losing the distinction between incomplete and unknown

An incomplete endpoint status is different from having no trustworthy terminal evidence. Combining both states under failed makes the retry policy less precise and makes incident reconstruction harder.

Classifying a stream from a partial event

Incremental content is not necessarily a completed result. A client that retries after an interrupted stream must account for any content already presented or consumed. Keep streaming completion checks separate from non-streaming response checks.

Allowing concurrent retries for one action

Two workers can each decide that the previous attempt is absent and send duplicate requests. Use an application-owned action identifier, retry counter, and synchronization boundary so only one worker can advance the action.

Logging too much

Full prompts and outputs are rarely required for a retry classifier. Prefer object type, endpoint status, field presence, sanitized error type, request identifier, and the decision reason. Keep credentials out of logs entirely.

Assuming endpoint contracts are interchangeable

Chat Completions and Responses expose different top-level structures. A generic parser that only looks for any text field can misclassify tool calls, incomplete responses, or unexpected objects as usable output.

Sources checked

• CometAPI documentation - accessed 2026-07-21; purpose: verify current CometAPI documentation navigation.
• CometAPI chat completions reference - accessed 2026-07-21; purpose: verify chat completion contract areas.
• CometAPI responses reference - accessed 2026-07-21; purpose: verify responses endpoint contract areas.
• CometAPI help center - accessed 2026-07-21; purpose: verify support and escalation documentation areas.

Contract details to verify

Reader next step

Implement the six-label classifier in an isolated route before changing retry behavior. Run one valid request and one controlled documented-error request for each endpoint family you use. Confirm that each attempt produces exactly one classification, one bounded retry decision, and a sanitized log record. Then review the decision table with the engineer who owns downstream side effects.

Do not enable automatic retries for unknown_outcome during this first pass. First verify that your application can reconcile the original action and prevent concurrent replays. Once that boundary is working, connect the classifier to your retry cap and incident escalation process.

When you are ready to test the integration against your approved configuration, Start with CometAPI .

FAQ

Is every non-200 response safe to retry?

No. Capture the documented error or observed failure first. The same request may fail again if the cause is tied to its parameters, credentials, account configuration, or another non-transient condition.

Is every 200 response a final success?

No. Verify the endpoint-specific object, terminal state, and required output used by your application. A recognizable but incomplete or malformed object should not be committed as usable work.

Should Chat Completions and Responses share one classifier?

They can share top-level labels and logging fields, but they should use separate endpoint validators. The object structures and lifecycle signals are not interchangeable.

What should happen after unknown_outcome?

Preserve the original evidence, prevent concurrent replay, and follow an application-specific reconciliation or escalation path. Do not assume that the remote operation had no effect merely because the client lacks a complete response.

What evidence should be sent to support?

Send sanitized request metadata, endpoint family, observed status, request identifier when available, classification, retry count, and concise reproduction steps. Do not include credentials, complete prompts, complete outputs, or unrelated user data.

When can the application retry automatically?

Only when the classification is eligible under a documented application policy, the retry cap has not been reached, and the operation can be repeated without unacceptable duplicate effects. The classifier supplies evidence; your application policy owns the final decision.