The Python SDK’s move toward metadata-only diagnostics should not mean losing the context needed to investigate a CometAPI failure. For an application using that SDK with CometAPI, the useful boundary is SDK diagnostics for SDK troubleshooting; a separate, allowlisted application record for CometAPI retry and routing decisions. Do not compensate for missing context by turning payload logging back on.
What the release establishes—and what it does not
The openai-python v3.4.0 release notes list “keep Python SDK diagnostics metadata-only,” linked to #3685 and commit 600aa8d.
That is a narrow release statement, not a field-by-field diagnostic schema. It does not establish what your application logger, tracing exporter, exception handler, or transport captures. Nor does it prove that every CometAPI model route exposes the same diagnostic fields. This is a support-record design recommendation, not a report of a tested integration.
A minimal sanitized CometAPI support record
CometAPI’s official error-handling guide recommends recording status, error code, request ID, model, attempt count, delay, and fallback reason without saving secrets. That is an English paraphrase of the Japanese guide’s logging guidance—not a promise that the SDK generates those fields automatically.
Use that list as an application-owned allowlist for the CometAPI retry/fallback workflow below, not as a description of SDK diagnostic output:
| CometAPI support-record field | What to retain when investigating a request, retry, or fallback |
|---|---|
| Status | The observed HTTP status, or an explicit unavailable value if no response arrived. |
| Error code | The observed code when present; do not substitute a guessed code or copy the entire error body. |
| Request ID | The observed identifier when available; missing is not evidence that no request occurred. |
| Model | The model identifier requested for that attempt, not an inferred underlying deployment. |
| Attempt count | A count with a documented scope, such as attempts initiated by the application. Do not imply visibility into hidden retries. |
| Delay | The retry delay chosen by the application, with units. Distinguish it from elapsed response time. |
| Fallback reason | A short, controlled reason for an application fallback decision, rather than a free-text exception dump. |
The entries above are a proposed implementation of the guide’s list. They deliberately separate observed response metadata from application decisions. If the application cannot observe a value, mark it unavailable rather than reconstructing it from assumptions.
This matters when investigating a CometAPI request that led to a retry or a model fallback: a request ID alone does not describe which model the application requested or why it chose another attempt. Conversely, an application attempt counter cannot establish how many underlying requests occurred. Preserve that distinction in the support handoff.
Apply the record to a CometAPI routing decision
For a CometAPI application with an explicitly configured fallback route, use the same official guide to choose what the support record must explain. The guide says a 401 should not trigger model fallback: fix or reload the API key instead. Its default for a 404 is also no fallback; check the base URL or endpoint first. A sanitized record should therefore distinguish an authentication or endpoint failure from a decision to try another model. Keep the observed status and available error code alongside the requested model, attempt count, and controlled fallback reason; never include the key or a full exception body as proof.
As a proposed local check, inject a simulated 401 into the application policy and verify that the CometAPI support record shows the attempted model and a controlled no-fallback reason, with no second model call. Repeat for a simulated 404 using the default no-fallback policy. These are tests to run, not results obtained here. This turns the guide’s logging list into an acceptance criterion for the application-owned record: it must explain why routing stopped even when SDK diagnostics omit payloads. It does not establish that CometAPI or the SDK automatically emits this record.
Check the sharing boundary separately
Before adopting this design, identify which layer owns retries and fallback decisions. If those decisions are hidden from the application, leave that context explicitly unavailable; do not fill the gap with a payload dump.
Before sharing a support artifact, inspect a locally generated, non-sensitive test case and its export path. The intended record should omit prompts, generated responses, credentials, full headers, and unfiltered exception text. Check tracing and exception exporters separately; an allowlisted support record does not sanitize their output.
Treat unexpected payload capture as a reason to stop sharing and fix the exporter, not as useful extra troubleshooting detail. Metadata can still contain sensitive identifiers, so apply an explicit access and retention policy even when the field allowlist passes.
The practical CometAPI workflow decision is to retain the official guide’s model, retry, and fallback context outside SDK diagnostics while keeping payloads out of the support package. The SDK release motivates the boundary; it does not enforce that boundary for the rest of the application.