What to Put in a Bug Report to an Aggregator: Request ID, Model, Timestamp, Payload Shape

Why a Minimal Reproducible Report Matters

When you use a no-login aggregator that accepts USDC on Base and issues API keys without KYC, support cannot browse your account history. They rely entirely on what you provide. A report that includes a request ID, model identifier, timestamp, and payload shape lets them locate the exact call in their logs—without needing access to your full conversation or payment details.

The Four Essential Fields

1. Request ID

Most aggregators return a unique request ID in the response headers (e.g., X-Request-ID) or in the error body. This ID is the primary key support uses to trace a call. If you did not capture it, check your client logs or the raw HTTP response.

• What to include: the exact string, copied verbatim.
• Why: it pinpoints one request among many, even across different API keys.

2. Model Name

Use the exact model identifier from the aggregator's documentation (e.g., claude-3-5-sonnet, gpt-4o, deepseek-chat). Do not use marketing names or aliases that may map to different versions.

• What to include: the model string you passed in the request body.
• Why: model routing and versioning differ; the exact string helps support reproduce the call with the same backend.

3. Timestamp (with Timezone)

Provide the time the request was sent, in ISO 8601 format with UTC offset. If you only know local time, convert to UTC or state the offset explicitly.

• What to include: e.g., 2025-03-21T14:32:10Z or 2025-03-21T14:32:10+02:00.
• Why: aggregators log in UTC; an approximate local time without offset can widen the search window unnecessarily.

4. Payload Shape

Describe the structure of your request without sharing the full content. For example: "JSON body with model, messages (array of 2 objects with role and content), temperature, and maxtokens." If the issue is about a specific parameter (e.g., tools, stream, responseformat), mention it explicitly.

• What to include: the top-level keys and types, plus any unusual values (e.g., empty messages, very long max_tokens).
• Why: many errors stem from malformed payloads or unsupported parameters. Shape reveals the cause without exposing private data.

Optional but Helpful Additions

• Error message and status code: copy the exact text and HTTP status (e.g., 400 Bad Request, 429 Too Many Requests).
• SDK/library and version: e.g., openai-python v1.30.0.
• Retry behavior: whether the error is consistent or intermittent.
• Redacted payload example: replace sensitive strings with placeholders, but keep structure and lengths.

A Copy-Paste Template

**Request ID:** [exact string]
**Model:** [exact model identifier]
**Timestamp:** [ISO 8601 with timezone, e.g., 2025-03-21T14:32:10Z]
**Payload shape:** [top-level keys and types, e.g., JSON with model, messages (array of {role, content}), temperature, max_tokens]
**Error:** [status code and message]
**SDK/version:** [if applicable]
**Notes:** [any other context, e.g., intermittent vs consistent]

What Not to Include

• Full API keys (revoke and rotate if exposed).
• Complete message histories or user data.
• Payment transaction hashes unless the issue is billing-related.

How Support Uses These Fields

Given a request ID and timestamp, support can query their logs for that specific call, check the model routing, inspect the payload shape for validation errors, and compare against known issues. Without these, they may need to ask for more information, delaying resolution.

Final Tip

Log the request ID and timestamp on your side for every call, at least during development. A small middleware that appends these to your application logs makes future bug reports trivial to produce.