How Do You Write a Reproducible AI API Bug Report?

OPERATIONS & SUPPORT · BLOG 160

By Token360 · Editorial review: November 5, 2026

A useful AI API bug report identifies one failing operation, gives the smallest safe request that demonstrates it, and separates expected behavior from observed results. Include the exact model ID, endpoint, timestamps, available request or job IDs, and sanitized evidence. If you cannot reproduce the problem, say so; a traceable intermittent incident is still worth reporting.

The starting question comes from OpenRouter’s FAQ on filing a bug report or change request. A support channel tells you where to ask; it does not determine whether the next person can reconstruct the failure. This guide focuses on that handoff for teams integrating Token360 and other model APIs.

It is not a service-level agreement, a claim about support response times or a catalog of model defects. The examples below are hypothetical. No live incident, paid generation or resolution-time benchmark was run for this article.

Read first: use Token360’s model capability guide to establish what the selected model actually supports. An undocumented expectation should be reported as a question or feature request, not presented as an established regression.

What should the first paragraph of the report say?

Describe the operation, the observable failure and the current impact in plain language. State when it happened and whether it is still occurring. Avoid leading with an assumed root cause. A support engineer should be able to tell what to investigate before opening attachments or asking which model and environment were involved.

“The AI is broken” does not identify a testable condition. “Our staging client receives a validation error when submitting this documented parameter to this model” does. The second statement still needs evidence, but it gives the investigation a starting point.

Weak report	More useful hypothetical report	What changed?
Video API is down.	The submit request returned a job ID. Our client stopped waiting before recording a terminal state. We do not yet know whether the job completed.	Separates client behavior from unknown server state.
The model ignored everything.	The output contains the requested object, but the specified action is absent in the attached time range. The original prompt and settings are included.	Identifies an output criterion instead of a general quality complaint.
It worked yesterday.	The previous client release accepted the same synthetic payload. Here are both versions and sanitized request bodies; the model ID is unchanged.	Provides a comparison without claiming what caused the difference.

Impact should be measured within a stated window: affected operations, affected workflow and available workaround. If you do not have a count, use “count unknown” rather than estimating a failure rate. A serious production interruption should be escalated through the agreed channel without waiting to build a perfect reproduction.

Which identifiers and timestamps should you include?

Include identifiers with their type and the timestamp of the event they describe. An application operation, an HTTP attempt and an asynchronous job can have different IDs. Preserve those distinctions in the report. If the response never supplied an ID, record that absence and provide the client’s time window and available connection evidence.

Prefer an unambiguous timestamp with timezone, such as 2026-11-05T10:15:30Z. That timestamp is illustrative, not an incident in this article. Keep start and end times separate when the report concerns a timeout or a long wait.

Reference	Purpose in the report	What it does not prove
Application operation ID	Groups the user task and its attempts in your system.	That the provider received any attempt.
Returned request or trace ID	Helps the service locate the relevant exchange where supported.	That the downstream generation finished.
Job ID	Identifies asynchronous work for status investigation.	That the output met the acceptance criteria.
Client error and timestamp	Documents what the caller observed when no response is available.	The provider’s final execution or billing state.

Token360’s security documentation recommends retaining request and trace IDs without the API-key secret. Supply actual identifiers only through a channel appropriate for your organization’s data policy. Never relabel a locally generated ID as a provider request ID.

If the client retried, list the attempts separately. One screenshot of the last error can hide an earlier accepted request. This article does not prescribe a retry strategy; it asks the report to make any retries already performed visible.

How do you reduce a request without losing the failure?

Start with a preserved copy of the original evidence, then remove one nonessential element at a time in an authorized test environment. Record whether the same symptom remains after each change. A shorter request is a useful reproduction only if it still demonstrates the relevant issue; otherwise, it is a different test.

The sitespeed.io project’s bug-report guidance emphasizes runnable commands, environment versions, text logs and expected versus actual behavior. For an AI API, adapt that principle to the selected model’s request contract rather than copying another project’s flags or public-upload instructions.

For example, first remove unrelated application code while keeping the model ID and body unchanged. Then replace a confidential input with an approved synthetic input. Finally, simplify optional fields one at a time. Keep a short change record: what was removed, what was retained and whether the failure persisted.

If replacing the private document makes the failure disappear, do not describe the sanitized request as a reproduction. Label it “safe comparison; original failure not reproduced.” Support may need a different approved way to inspect the relevant input characteristic, such as file structure, dimensions or encoding.

Do not run repeated billable generations simply to make a report look rigorous. Existing request records can be enough to start an investigation. If a retest is justified, define its scope and record the actual result, including failures to reproduce. A fixed seed alone does not establish that every aspect of a generated output will repeat.

What should you redact before sending evidence?

Remove credentials and unrelated private content while preserving the request structure needed to understand the problem. Review commands, headers, query strings, logs, screenshots and media separately. Redaction is not complete just because the API key was removed from one code block; attachments can contain copies of the same secret or private access links.

Material	Keep for diagnosis	Remove or restrict
Request	Method, endpoint path, model ID and relevant parameter names/types.	Authorization values, session cookies and secret query parameters.
Response	Status, relevant error text and appropriately shared correlation IDs.	Unrelated customer data or embedded private content.
Media reference	Artifact type, dimensions, duration and defect location.	Public exposure of signed URLs or confidential assets.
Client environment	SDK/runtime versions and relevant proxy or timeout settings.	Complete environment files and unrelated account configuration.

Use placeholders that preserve data types: a replacement string should remain a JSON string. Do not “clean up” a malformed value that is the subject of the report. Explain each alteration so the investigator can distinguish the real request from the sanitized representation.

Token360’s data-handling guidance includes support material among the data types whose handling needs review. Sending an attachment creates another copy; do not assume an inference retention setting governs a support upload. Use the current account agreement and approved support path for confidential evidence.

How does the evidence change for text, images, audio and video?

Match the attachment to the observed failure. A protocol error needs the exchange and client context; a generated-media complaint needs the original artifact and a precise acceptance criterion. Separate file properties from perceptual judgments. Record which checks were actually performed so that an untested audio track or unseen frame range is not treated as verified.

For text, include the smallest relevant prompt and response excerpt, the expected format or behavior, and the reason the result fails. If the issue concerns a tool call, retain the relevant call/result pairing in sanitized form rather than showing only the final assistant sentence.

For images, provide the relevant input characteristics and mark the observed output defect. For video, identify time ranges and whether the review used continuous playback or sampled frames. For audio, state what was heard and how it differed from the request; the presence of an audio track alone says nothing about dialogue correctness.

A useful distinction is “requested output parameter was rejected” versus “generation completed, but the action looked wrong.” The first may concern request compatibility. The second needs the prompt, settings and result to evaluate. Neither observation by itself proves that a gateway, publisher or model is uniquely responsible.

If only a downloaded or edited copy is available, identify it as such. Trimming, transcoding or replacing a soundtrack can change the evidence. Keep the original artifact where permitted and explain any derived version sent for convenience.

What does a complete report template look like?

A practical template combines a short summary with structured references, reproduction steps and evidence boundaries. It should allow “unknown,” “not retested” and “not returned” rather than forcing invented values. Finish with one concrete question for support, such as locating a request or confirming whether the reported behavior matches the documented contract.

Copy blog160-bug-report-template.txt:

AI API BUG REPORT — blank working template

Summary: [operation + observable failure]
Environment: [production/staging; application and SDK versions]
Platform / endpoint / method: [exact destination, no secrets]
Public model ID: [exact request value]
First observed / last observed: [ISO 8601 timestamps with timezone]
Impact: [measured affected operations; time window; unknowns]

Expected: [specific documented behavior or acceptance criterion]
Actual: [status, error code, output difference; no inferred cause]

Identifiers (label each type):
- Application operation ID:
- API request / trace ID, if returned:
- Async job ID, if returned:
- Attempt IDs / timestamps:

Steps to reproduce:
1. [starting configuration and safe synthetic input]
2. [sanitized request or minimal code with credential placeholder]
3. [observation and where it is recorded]

Reproduction status: [reproduced / intermittent / not retested]
Original vs reduced request: [what changed and whether failure remained]
Observed attempts: [actual count and results; do not estimate]
Last known working configuration: [or unknown]

Evidence:
- Sanitized request:
- Status / error response or client error:
- Relevant logs, with time boundaries:
- Media artifact and exact timestamp if relevant:
- Where processing is confirmed / where state is unknown:

Redaction and sharing:
- Removed credentials, cookies, signed URL tokens, private content:
- Remaining confidential material and approved sharing channel:
- Differences introduced by sanitization:

Question for support: [one concrete next action]
Retest / resolution: [date, exact change, comparable result, remaining unknowns]

. The blank template covers environment, model, timestamps, identifiers, expected and actual results, minimal reproduction, redaction and retest. It is an editorial working aid, not an official mandatory Token360 support form.

Summary: [operation + observable failure]
Model / endpoint / client version: [exact values]
When: [timestamp and timezone]
References: [label request, job and application IDs]
Expected: [specific criterion or documented behavior]
Actual: [observed result, without guessed root cause]
Reproduction: [sanitized request and numbered steps]
Status: [reproduced / intermittent / not retested]
Attachments: [relevant evidence and redaction notes]
Question: [the next decision needed]

For Token360, verify the exact public ID against the model catalog and include the endpoint you actually called. Do not substitute a friendly display name for the request value. If a Playground attempt and an API attempt differ, include both parameter sets instead of describing them as identical.

Keep related evidence in one case and label follow-up changes. A new model, different prompt and upgraded SDK tested simultaneously can provide a workaround, but cannot isolate which change mattered. That limitation belongs in the report.

When is a bug report ready to close?

Close the loop by recording the exact change and a comparable retest, or by documenting why the issue remains unresolved. Distinguish a confirmed fix from a workaround and from an incident that stopped reproducing. A successful unrelated request is not sufficient evidence that the original failure condition has been addressed.

If support identifies an unsupported parameter, record the documented replacement and which application configuration was updated. If the failure cannot be reproduced again, preserve the original evidence and say that the cause remains unconfirmed. Do not convert “not seen in the retest” into a platform-wide reliability claim.

For an ongoing incident, report the new time window and identifiers instead of overwriting the earlier record. For a billing question, attach the relevant usage reference and keep the question separate from an assumption that a failed client request must have been free.

Read next: Token360’s billing and usage documentation helps investigate the financial record separately from the technical symptom. Company context is available through About Token360. This guide does not promise a response time or contractual remedy.

For the adjacent review, diagnose browser-only CORS failures and verify the exact model identifier. Keep these questions distinct from this article’s scope.

Frequently asked questions

A report can be useful before its cause is known. The important distinction is between evidence already captured, steps actually repeated and explanations still being tested. These answers address common handoff questions; they do not replace the support arrangements, data-sharing permissions or incident procedures that apply to a particular enterprise account.

Can I report a problem without a request ID?

Yes. State that no ID was returned or captured. Include the endpoint, model, client error, timestamp with timezone and any job or application reference you do have.

Is a screenshot enough?

Usually it is supporting evidence. Include searchable error text and sanitized request details when available. For visual defects, screenshots help locate the issue but may not show motion or audio.

Should I share the API key so support can reproduce it?

No. Provide the request with a credential placeholder and relevant non-secret references through the approved channel. Authentication for any authorized retest should use the appropriate controlled account setup.

Do I need three failed generations before asking for help?

No. There is no sample-count requirement in this guide. Report the observations you already have, and do not infer a model-wide failure rate from them.

Does a better report guarantee a faster fix?

No measured guarantee is made here. The objective is to remove ambiguity and provide usable evidence; investigation and resolution still depend on the issue and applicable support arrangements.