CometAPI Timeout Evidence Pack for On-call Reviews

Last reviewed: 2026-06-17

Direct answer

When a CometAPI timeout surfaces during an on-call shift, the fastest path to resolution is a pre-assembled evidence pack: a short set of HTTP span fields, request metadata, and retry history that lets you answer the three questions a review needs — was the timeout on the client side or the server side, was a retry safe, and what signal do you hand to support?

This guide walks through each layer of that evidence pack: which OpenTelemetry HTTP span attributes to record, how to apply exponential backoff without amplifying load, what the CometAPI chat endpoint contract areas are, and how to escalate through the help center when evidence is inconclusive.

For a complementary view of how these timeout signals feed into broader fallback routing, see Timeout-budget fallback checks for chat completions.

For broader release checks, see CometAPI chat reliability contract review.

Who this is for

• On-call engineers who need a fast, repeatable evidence-capture checklist when a CometAPI chat call times out.
• Platform engineers building or hardening a retry layer around CometAPI endpoints.
• Reliability engineers preparing post-incident documentation that must cite specific HTTP signals rather than vague “it was slow” observations.

This guide assumes you already have a working integration with the CometAPI chat completions endpoint and that your infrastructure emits HTTP spans. Exact endpoint paths, authentication schemes, and field names should be verified against the current official docs linked in the Sources section.

Key takeaways

1. Capture the right five span fields first. HTTP method, URL, status code, response duration, and error type are the minimum evidence set. Everything else — request ID, retry count, upstream hop timing — is supplementary.
2. Distinguish client timeout from server timeout before retrying. A client-side timeout (your configured deadline fires before the server responds) does not necessarily mean the server processed nothing. Retrying without idempotency checks can produce duplicate charges or duplicate completions. Verify the contract areas listed in this guide before assuming safety.
3. Exponential backoff with jitter is the standard retry shape. The AWS prescriptive guidance on retry-with-backoff recommends capping retry attempts, adding per-attempt jitter, and respecting any Retry-After signal from the server. Do not implement a flat retry loop against an LLM inference endpoint.
4. Log a structured evidence record immediately. The log-record template at the end of this guide gives you a copy-paste starting point. Fill it during the incident, not after.
5. Escalate to the help center with evidence, not symptoms. The CometAPI help center is the correct escalation path. Support engineers move faster when you arrive with span IDs, status codes, and a timeline rather than a description of what the user saw.

Understanding timeout categories for CometAPI calls

LLM inference calls have unusually long tail latencies compared with typical REST APIs. A timeout on a chat completions request may fall into one of three categories, each requiring different evidence and a different retry posture:

Connect timeout — the TCP connection to the endpoint did not complete within your configured window. This is almost always safe to retry immediately. The span will show no HTTP status code and the error type will be a network-level exception.

Read timeout (client-side deadline) — the connection succeeded and the request was sent, but your client’s read deadline fired before the response completed. The server may have partially or fully processed the request. This category requires idempotency verification before retry. The span will show no HTTP status code or may show a partial stream termination.

Server-returned error status — the server responded with an HTTP error code (for example, 429, 500, 502, 503). The exact retry behavior depends on the status code. A 429 should be accompanied by a Retry-After header if one is documented; a 502 or 503 suggests a transient infrastructure issue. Verify the current contract behavior in the CometAPI chat completions reference before coding retry logic against these codes.

Which category a timeout falls into determines which fields matter most in your evidence pack.

The five-field minimum evidence set

OpenTelemetry HTTP semantic conventions define a standard vocabulary for HTTP spans. For on-call evidence packs, capture at least:

The exact attribute names and their cardinality guidance should be verified against the OpenTelemetry HTTP semantic conventions current at the time of your integration. The spec evolves; attribute names seen in older agent versions may differ.

Supplementary fields that strengthen an evidence pack:

• Request ID or trace ID returned by the server (verify the response field name in the CometAPI docs)
• Retry attempt count for the current request sequence
• Wall-clock timestamps for each attempt (not just span duration)
• Any Retry-After value received from the server

Applying retry-with-backoff safely

The AWS prescriptive guidance on retry-with-backoff describes the general pattern: start with a short initial delay, double the wait on each subsequent failure, add per-attempt random jitter, and cap the maximum number of attempts. The goals are to avoid thundering-herd amplification when a service is degraded and to give the upstream time to recover.

For LLM inference specifically, additional care is needed:

• Set a maximum attempt budget. LLM calls are expensive. An unbounded retry loop can exhaust quota and inflate cost without improving success rate. Choose a maximum that reflects acceptable latency, not just acceptable failure rate.
• Check for a Retry-After signal before applying your own backoff. If the server sends a Retry-After header, use that value as your minimum wait. Overriding it with a shorter interval may worsen a rate-limit condition.
• Do not retry on streaming reads that have already begun. Once the server has started streaming a response, a mid-stream timeout means partial output was delivered to your application layer. Retrying produces a new independent completion, not a continuation.
• Record each attempt in your evidence pack. Each attempt’s status code, duration, and error type is a separate evidence row. Reviewers need the full sequence, not just the final outcome.

Verify whether the CometAPI chat endpoint is documented as idempotent for your request shape before building an automatic retry. The endpoint contract areas to check are listed in the Contract details section below.

Smoke-test workflow

Setup assumptions

• You have a valid API key configured in your environment (do not hardcode credentials).
• Your HTTP client is instrumented to emit spans with at minimum the five fields listed above.
• You have a log sink that accepts structured JSON records.
• The CometAPI chat completions endpoint path is the one documented at https://apidoc.cometapi.com/api/text/chat — verify the path before running.

Happy-path request plan

1. Send a minimal well-formed chat completions request with a short, deterministic prompt (for example, ask for a single-word response).
2. Verify the response returns HTTP 200 and a non-empty choices array with a message object.
3. Record the five minimum span fields plus any request-ID field present in the response.
4. Log the structured evidence record using the template below.

Error-path check

1. Configure a deliberately short read timeout on your client (shorter than a realistic inference duration for a medium-length prompt).
2. Send a request designed to take longer than that timeout.
3. Verify your instrumentation captures: no HTTP status code (or the partial-stream termination code your client emits), the client-side duration at or near your timeout setting, and the error type field populated with a non-empty value.
4. Confirm the error is logged as a read_timeout category, not a connect_timeout or server error.
5. Do not assert on specific server-side response content when the timeout fires before delivery.

Minimum assertions

• Happy path: HTTP 200, non-null response body, span duration within your acceptable window.
• Error path: span captures the error type field, no HTTP status code is logged as a success, the attempt is recorded as a failed attempt in your evidence log.

Pass/fail logging fields to record

• attempt_number
• http_status (or null on connect/read timeout)
• error_type (or null on success)
• duration_ms
• timeout_category (connect / read / server_error / none)
• retry_safe (boolean, your assessment based on timeout category)

What the smoke test must not assert

• Do not assert on specific model identifiers in the response — these may change.
• Do not assert on exact response wording or token counts.
• Do not assert on latency percentiles in a smoke test; use a dedicated load test for that.
• Do not assert that a retry will succeed; assert only that your retry logic fires the correct number of times with the correct backoff shape.

Sanitized log-record template

Copy this template into your incident notes or structured log sink immediately after each attempt. Replace placeholder values with real observations; remove fields your stack does not emit.

{
  "record_type": "cometapi_timeout_evidence",
  "incident_id": "INC-PLACEHOLDER",
  "reviewed_at": "YYYY-MM-DDTHH:MM:SSZ",
  "site_or_service": "YOUR-SERVICE-NAME",
  "attempt_number": 1,
  "endpoint_path": "/api/text/chat",
  "http_method": "POST",
  "http_status": null,
  "error_type": "ReadTimeout",
  "timeout_category": "read",
  "duration_ms": 30000,
  "client_deadline_ms": 30000,
  "server_request_id": "PLACEHOLDER-IF-RETURNED",
  "trace_id": "PLACEHOLDER",
  "retry_safe": false,
  "retry_after_header": null,
  "notes": "describe what you observed in plain language"
}

Do not include API keys, full request bodies, personal data, or real prompts in incident records that may be shared with support or stored in shared log systems.

Escalating to CometAPI support

When your evidence pack is assembled and the timeout pattern is not resolved by a retry or a client-side configuration change, escalate through the CometAPI help center at https://apidoc.cometapi.com/support/help-center. Verify the current support contact and escalation process at that URL; the specific form fields and response channels may change.

What to include in a support escalation:

• The sanitized log records for each affected attempt (no credentials or personal data).
• The five-field span evidence for each attempt.
• The timeline: first occurrence, frequency, whether it is ongoing or resolved.
• Your client configuration: timeout settings, retry budget, streaming vs. non-streaming mode.
• What you have already tried and ruled out.

Support engineers move significantly faster with structured evidence than with symptom descriptions. The investment in assembling the evidence pack during the incident pays off at escalation time.

Failure modes

• Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
• Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
• Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
• Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
• Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.

Sources checked

• CometAPI documentation - accessed 2026-06-17; purpose: verify current CometAPI documentation navigation.
• CometAPI chat completions reference - accessed 2026-06-17; purpose: verify chat completion contract areas.
• CometAPI help center - accessed 2026-06-17; purpose: verify support and escalation documentation areas.
• AWS retry with backoff pattern - accessed 2026-06-17; purpose: verify retry and backoff guidance.
• OpenTelemetry HTTP semantic conventions - accessed 2026-06-17; purpose: verify HTTP telemetry field context.

Contract details to verify

The following areas are based on the sources listed above. Verify each claim against the current official docs before relying on it in production configuration or incident review documentation. Exact values, field names, and behavior may differ from what is shown here; the sources are the authoritative reference.

Reader next step

Compare the workflow against Start with CometAPI.

Use CometAPI chat reliability contract review as the next comparison point. Keep Timeout-budget fallback checks for chat completions nearby for setup and permission checks.

FAQ

Q: My client fired a read timeout but I never got an HTTP status code. Did the server process my request? A: A read timeout means your client deadline fired before the response was fully delivered. Whether the server processed the request depends on when in the lifecycle the deadline fired. If the connection was established and the request body was sent, the server may have received and begun processing it. Check for any request ID in partial response headers before assuming the request was not processed. This is the key reason to verify idempotency contract areas before retrying.

Q: How many retries are safe for a CometAPI chat call? A: The safe number depends on the timeout category, the documented behavior of the endpoint for your request shape, and your application’s latency and cost budget. General guidance from the AWS retry-backoff pattern recommends a small fixed cap (often 3 to 5 attempts) with exponential backoff and jitter. Verify the current CometAPI docs for any documented guidance specific to their endpoint.

Q: What fields should I include when escalating to support? A: At minimum: sanitized span evidence (status code, duration, error type), the timeline of affected requests, your client timeout configuration, and any request IDs returned by the server. See the Escalation section above for the complete list.

Q: Is this evidence pack format specific to CometAPI or usable with other LLM APIs? A: The core structure — HTTP span fields drawn from OTel semantic conventions, retry-backoff pattern from AWS guidance, and escalation with structured evidence — applies broadly to any HTTP-based LLM API. The specific endpoint paths, authentication, and support channels are CometAPI-specific and must be verified in the CometAPI docs.

Q: Where can I learn more about CometAPI? A: The official starting point is CometAPI.