How to Check the Responses Endpoint When Your Coding Agent Calls a Gateway

Last reviewed: 2026-06-06

Direct answer

When a coding agent calls a model gateway through the Responses endpoint, the check that matters most is straightforward: send a minimal well-formed request, confirm the HTTP status is in the 2xx range, confirm the response body contains a non-empty output item, and confirm the finish reason is what the request asked for. If any of those three assertions fails, the endpoint is not ready for agent traffic.

The Responses API is structured differently from the older chat completions endpoint. Instead of a choices array with message objects, the Responses API returns an output array. Your smoke test assertions must match the shape the Responses endpoint actually returns—not the shape your agent might have been written to expect from a different endpoint family. Checking this mismatch is the single most common source of silent failures when a gateway routes Responses traffic.

For exact request fields, required headers, authentication scheme, output object structure, and finish-reason values, verify the current contract in the CometAPI Responses endpoint reference. The body of this guide covers the operator workflow and what your checks must assert; the linked reference is the authoritative source for field names and values.

For broader release checks, see AI Coding Agent Setup, Security, and Model Routing .

Who this is for

This guide is for developers and platform engineers who:

• Are setting up or auditing a coding agent that routes model calls through an OpenAI-compatible gateway.
• Want a repeatable smoke-test procedure they can run after any gateway reconfiguration, model swap, or key rotation.
• Need to know which response fields to assert on, which error paths to exercise, and what a passing log record looks like.
• Are using a gateway such as CometAPI that exposes a Responses endpoint alongside a chat completions endpoint and need to keep the two separated in their agent config.

If you are still at the initial gateway setup stage, the Route Coding Agent Model Calls Without Endpoint Drift guide covers the full initial configuration workflow before you run endpoint checks.

Key takeaways

• The Responses endpoint and the chat completions endpoint return different response shapes. Assertions written for one will not reliably pass for the other.
• A minimal smoke test needs only three assertions: HTTP 2xx status, a non-empty output array in the response body, and a terminal finish reason. Anything beyond that is a bonus check.
• Error-path checks matter as much as happy-path checks. An endpoint that returns a helpful error message on a bad request is behaving correctly; an endpoint that silently returns 200 with an empty body is not.
• Log every smoke-test run with a timestamp, the endpoint base URL (no key), the HTTP status, the finish reason, and a pass/fail flag. Never log the full request body, the API key, or the raw response content.
• Exact field names, auth header format, and finish-reason vocabulary must be confirmed in the current gateway docs before your assertions are written. These details change across API versions and gateway providers.

Smoke-test workflow

Setup assumptions

Before running the check:

1. You have an API key for your gateway stored in an environment variable (for example GATEWAY_API_KEY). The key is never hard-coded in the test script.
2. Your agent config file points the Responses endpoint at the correct base URL. Verify this is the Responses path, not the chat completions path. The exact path format is documented in the CometAPI Responses reference.
3. You have confirmed which model identifier your gateway expects for Responses traffic. Check the CometAPI models overview for the current list. Do not assume a model ID carries over from the chat completions config.
4. Your test environment has outbound HTTPS access to the gateway base URL.

Happy-path request plan

Construct a minimal request with:

• The correct endpoint path for the Responses API (verify in docs; do not guess).
• An Authorization header using the format specified in the gateway docs. The exact scheme (for example Bearer vs a custom prefix) must match what the docs specify.
• A model field set to a currently listed model identifier from the models overview.
• An input field containing a short, safe, non-sensitive prompt. Keep this short. You are testing the endpoint contract, not the model output quality.
• No other optional fields on the first run. Add fields only after the baseline passes.

Assert:

1. HTTP status is in the 2xx range.
2. The response body is valid JSON.
3. The output field exists and contains at least one item.
4. The finish reason on the output item is a terminal value as documented (verify the exact vocabulary in the Responses reference).

Error-path check

Send a second request with a deliberately malformed authorization header (for example, omit the header entirely or send a clearly invalid value). Assert:

1. HTTP status is 4xx (typically 401 or 403).
2. The response body is valid JSON containing an error field or error message.
3. The response does not contain any output items.

If this request returns 200 or returns output despite the bad auth, stop. The gateway is misconfigured and must not receive agent traffic until the issue is resolved.

Minimum assertions

Pass/fail logging fields

After each smoke-test run, write one log record. Include only these fields:

smoke_test_run_id: timestamp_utc: endpoint_base_url: endpoint_path: model_id_used: http_status: output_item_count: finish_reason: error_field_present: <true|false> pass: <true|false> notes:

Do not include: the API key, the request body text, the full response body, token counts, latency, pricing, or any personal data.

What the smoke test must not assert

• The exact wording or content of the model’s output. Output content is non-deterministic and will cause flaky tests.
• Specific token counts or response length. These vary by model version.
• Specific latency or response time. Gateway latency varies and is not a correctness signal.
• Pricing or billing fields. These are not part of the endpoint contract check.
• Model availability or uptime. Availability is a separate operational concern.

Sanitized log-record template

Copy this template into your test runner output. Replace all angle-bracket placeholders with observed values. Never substitute real prompts, real API keys, full response bodies, or commercial account details.

smoke_test_run_id: run-YYYYMMDD-001
timestamp_utc: "YYYY-MM-DDTHH:MM:SSZ"
endpoint_base_url: "https://gateway.example.com"
endpoint_path: "/api/text/responses"
model_id_used: "<model-id-from-gateway-docs>"
http_status: 200
output_item_count: 1
finish_reason: "<terminal-value-from-docs>"
error_field_present: false
pass: true
notes: "Baseline happy-path check after config update."

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

• OpenAI Codex cloud documentation - accessed 2026-06-06; purpose: verify hosted coding-agent workflow context.
• OpenAI Codex AGENTS.md guidance - accessed 2026-06-06; purpose: verify repository instruction-file context for coding agents.
• CometAPI documentation - accessed 2026-06-06; purpose: verify current CometAPI documentation navigation.
• CometAPI responses reference - accessed 2026-06-06; purpose: verify responses endpoint contract areas.
• CometAPI models overview - accessed 2026-06-06; purpose: verify model catalog discovery guidance.
• CometAPI help center - accessed 2026-06-06; purpose: verify support and escalation documentation areas.

Contract details to verify

Reader next step

Compare the workflow against Start with CometAPI .

Use AI Coding Agent Setup, Security, and Model Routing as the next comparison point. Keep Triage CI Failures With a Coding Agent Without Losing the Evidence nearby for setup and permission checks.

FAQ

Q: My agent was working with the chat completions endpoint. Can I reuse the same assertions for the Responses endpoint?

No. The chat completions endpoint returns a choices array; the Responses endpoint returns an output array. Assertions copied from chat completions tests will either fail silently or produce false positives on Responses traffic. Write new assertions that match the shape documented in the Responses reference.

Q: How often should I run these smoke tests?

Run them after any change that could affect the gateway path: key rotation, model config update, gateway version upgrade, or environment variable change. For long-running agent pipelines, a lightweight scheduled check that logs pass/fail without logging content is reasonable practice.

Q: What if the gateway returns 200 but the output array is empty?

Treat this as a failure. An empty output array with a 200 status is not a successful Responses call. Check the model identifier, the request body structure, and the gateway routing config. If the issue persists, use the CometAPI help center to escalate.

Q: Should I test with a production API key or a test key?

Use a dedicated non-production key for smoke tests wherever your gateway supports it. Never hard-code any key in test scripts. Store keys in environment variables and exclude them from logs.

Q: The finish reason in the response is not one I recognize. Is that a problem?

Yes. Unrecognized finish reasons indicate either a gateway version mismatch or a request that triggered an unusual termination condition. Check the finish-reason vocabulary in the Responses reference and verify your gateway version matches the docs you are reading.

Q: Can I use CometAPI as a gateway for Responses endpoint traffic from a coding agent like Codex?

CometAPI exposes a Responses endpoint alongside its other model routes. Whether a specific coding agent’s cloud environment supports routing to a third-party gateway depends on that agent’s configuration options. Verify the current gateway setup path in the CometAPI Responses reference and check CometAPI for current integration options.