Source pack

• Primary contract source: CometAPI chat API documentation, used to verify the current chat request and response contract.
• Documentation entry point: CometAPI API documentation home, used to confirm where operators should begin when checking current API documentation.
• Support escalation source: CometAPI help center, used when endpoint behavior, account limits, billing, or error handling needs confirmation beyond the visible API page.
• Refresh continuity source: Existing preview article for this in-place refresh, used to preserve the existing URL and avoid creating a new page.

Intent brief

Operator intent: Confirm whether an incident came from a mismatch between your application’s assumed chat-completions contract and the current CometAPI documentation.

Who this is for: This is for engineers, SREs, and integration owners who already have a CometAPI chat integration in service and need a disciplined post-incident contract review.

Success criteria: By the end of the review, you should have a documented answer for each contract layer: endpoint path, authentication header, request body, response shape, error behavior, and any rate-limit or billing assumptions that your application depends on.

Review a CometAPI chat completions contract

Last reviewed: 2026-06-09

A chat completions incident is not always a model-quality issue. It can be a contract issue: the application sends a field the API no longer accepts, assumes a response field exists, retries the wrong error class, or records billing data from the wrong place.

Use the CometAPI chat API documentation as the primary source for the live contract, then use the CometAPI help center when account-specific behavior, support guidance, or undocumented edge cases need confirmation.

For broader integration material, keep the CometAPI tutorials index and the CometAPI tutorials post archive nearby while you update runbooks.

Key takeaways

• Treat the chat completions contract as an operational artifact, not just client code.
• Verify every assumed endpoint, header, request field, response field, and error behavior against the current CometAPI documentation.
• Do not infer rate limits, pricing, billing fields, or model availability from one successful request.
• Keep incident replay tests sanitized and deterministic enough to compare before-and-after behavior.
• When the docs do not expose an exact value, mark it as “to verify” instead of inventing it.

Concise definition

A CometAPI chat completions contract is the documented agreement your application relies on when it sends a chat-style request to CometAPI and parses the response. In operations, that contract includes the endpoint path, authentication format, required and optional request fields, response structure, error surface, retry expectations, and any account-level assumptions that affect production behavior.

When to run this review

Run a contract review after any incident where one of these was true:

1. Requests reached CometAPI but returned unexpected validation, authentication, or server errors.
2. Responses were successful but your parser failed.
3. Streaming or non-streaming behavior changed from what your application expected.
4. Retries amplified the issue instead of recovering.
5. Usage, cost allocation, quota, or account-limit reporting did not match your internal assumptions.
6. A client library, gateway, proxy, prompt service, or model configuration changed near the incident window.

This is not a generic smoke test. The goal is to reconstruct the exact contract your production system assumed at the time of failure and compare it with the current documented contract.

Contract details to verify

Use this table as the incident review worksheet. The values below are intentionally phrased as verification targets because the prompt source did not provide exact endpoint paths, auth schemes, field names, error codes, rate limits, prices, or billing fields.

Incident review workflow

1. Freeze the incident evidence

Before changing code, save the operational facts:

• Incident start and end time.
• Affected services and environments.
• Sanitized request sample.
• Sanitized response or error sample.
• Client library version or HTTP client wrapper version.
• Gateway, proxy, or middleware changes.
• Retry count and backoff behavior.
• Any request IDs, trace IDs, or internal correlation IDs that are safe to store.

Do not store raw prompts, secrets, customer data, or full authentication headers in the review document.

2. Separate transport failure from contract failure

Classify the failure before assigning cause:

• Transport issue: DNS, TLS, timeout, network policy, proxy, or gateway failure.
• Authentication issue: missing header, expired token, wrong secret, wrong environment.
• Request contract issue: missing required field, unsupported field, malformed message structure.
• Response contract issue: parser expected a field, type, array, or nested object that was absent or different.
• Error contract issue: application retried an error that should have failed fast, or failed fast on an error that should have been retried.
• Account assumption issue: rate limit, billing, quota, or account-state assumption not confirmed by docs or support.

Only the middle four categories are true chat-completions contract failures, but all six belong in the review.

3. Compare production configuration to docs

Open the CometAPI API documentation home first if you need to confirm the current documentation tree, then inspect the chat API page.

Create a two-column diff:

If the right column is blank, the assumption is not production-safe yet.

4. Replay one sanitized request

Use a controlled request that does not include customer content. Replace every placeholder only after checking the current documentation.

curl -sS -X POST "<COMETAPI_BASE_URL_FROM_DOCS><COMETAPI_CHAT_PATH_FROM_DOCS>" \
  -H "<AUTH_HEADER_FROM_DOCS>: <TOKEN_FROM_SECRET_STORE>" \
  -H "<CONTENT_TYPE_HEADER_FROM_DOCS>" \
  -d '{
    "<MODEL_FIELD_FROM_DOCS>": "<VALIDATED_MODEL_ID>",
    "<MESSAGES_FIELD_FROM_DOCS>": [
      {
        "<ROLE_FIELD_FROM_DOCS>": "<USER_ROLE_VALUE_FROM_DOCS>",
        "<CONTENT_FIELD_FROM_DOCS>": "Return one short sentence confirming this contract replay."
      }
    ],
    "<OPTIONAL_PARAMETERS_FROM_DOCS>": "<ONLY_INCLUDE_IF_VALIDATED>"
  }'

Use this replay to confirm the contract, not to benchmark latency or infer rate limits. If your incident involved streaming, run a separate replay that matches the documented streaming contract after you verify the relevant field names and response framing.

5. Test parser behavior with guarded expectations

A robust parser should distinguish between:

• Required response fields that must exist for your service to continue.
• Optional fields that may be absent.
• Unknown fields that should not break parsing.
• Error bodies that should bypass normal response parsing.
• Streaming chunks and final messages, if your integration supports both.

Do not assume a token, usage, billing, or model metadata field exists unless the CometAPI documentation or support confirmation supports that assumption.

6. Recheck retry and fallback logic

For each error class your service saw during the incident, document:

• Whether the request reached CometAPI.
• Whether retrying is safe for that operation.
• Whether the client retries on authentication or validation errors.
• Whether retries preserve the same request body.
• Whether fallback changes request fields or only changes the selected model or route.
• Whether fallback behavior is documented in your own runbook.

Treat any retry threshold as local policy unless the source explicitly documents a required value.

7. Close the review with contract changes

End the review with specific updates:

• Configuration change required: yes/no.
• Client code change required: yes/no.
• Parser change required: yes/no.
• Retry policy change required: yes/no.
• Monitoring or alert change required: yes/no.
• Documentation or runbook change required: yes/no.
• Support follow-up required: yes/no.

If support confirms a behavior that is not visible in public docs, record the date, ticket reference, and exact operational interpretation in your internal runbook.

Validation checklist

Use this as the final sign-off list.

• Endpoint path checked against the current chat API documentation.
• Base URL source identified and environment-specific overrides reviewed.
• Authentication header name and token format verified.
• Request body diffed against documented fields.
• Response parser checked against documented response shape.
• Streaming behavior checked separately if used.
• Error body handling tested with at least one safe negative case.
• Retry policy reviewed for validation, auth, timeout, and server-side errors.
• Rate-limit assumptions marked as documented, support-confirmed, or unknown.
• Billing or usage assumptions marked as documented, support-confirmed, or internal estimate.
• Sanitized replay stored with the incident record.
• Runbook updated with the verified contract.

Documentation handoff template

Copy this into your internal incident record.

CometAPI chat completions contract review

Incident:
Owner:
Review date:
Environment:

Verified sources:
- Chat API docs:
- Docs home:
- Support/help center:
- Support ticket, if any:

Endpoint:
- Base URL source:
- Chat path source:
- Gateway rewrite involved:

Authentication:
- Header verified:
- Secret source:
- Rotation or expiry issue:

Request contract:
- Required fields used:
- Optional fields used:
- Fields removed:

Response contract:
- Fields parsed:
- Optional fields guarded:
- Streaming behavior:

Errors:
- Observed status or error class:
- Retry decision:
- Fallback decision:

Rate-limit and billing assumptions:
- Documented:
- Support-confirmed:
- Unknown:

Changes shipped:
- Code:
- Config:
- Runbook:
- Monitoring:

FAQ

Is this the same as a smoke test?

No. A smoke test asks whether one request works. A contract review asks whether production assumptions match the documented API contract across success, error, parsing, retry, and accounting paths.

What if my code works but the field is not documented?

Treat it as an unsupported assumption until you verify it through the current CometAPI documentation or support. Guard the field as optional and avoid making critical business logic depend on it without confirmation.

Should I hard-code the endpoint path after this review?

No. Store the verified path in configuration or a maintained client wrapper, and document which source confirmed it. Hard-coding makes future reviews harder.

Can I infer rate limits from a burst test?

No. A burst test can reveal behavior in one moment, but it should not become a contract. Verify rate-limit assumptions through documentation or support.

What should I do if docs and support appear to conflict?

Pause the rollout or mitigation, preserve both references, and ask support for clarification. In the incident record, mark the contract item as unresolved until you have a single operational interpretation.

How often should this contract be reviewed?

Review it after incidents, after client or gateway changes, before major launches, and whenever your application begins relying on a new request field, response field, retry rule, or accounting assumption.

Sources checked

Ready to validate your integration against the current docs? Start with CometAPI.