Bug Report Template for API Products
API bugs are high-impact by default because they break downstream integrations that often power production workflows. A bug in a REST endpoint does not just affect one user — it affects every developer who has integrated with that endpoint. This makes API bug reports significantly more consequential than consumer UI bugs, and requires a correspondingly more rigorous reporting standard.
This template ensures that every API bug report includes the technical context required for immediate reproduction (not "I cannot reproduce it"), the customer impact analysis needed for prioritization, and the breaking change assessment that determines whether the fix itself might cause more problems than the bug. It is designed for teams building APIs, SDKs, and developer platform products.
Why API bug reports require a different standard
The fundamental difference between an API bug and a UI bug is the impact radius. When a consumer app button is broken, the users who encounter it have a bad experience. When an API endpoint returns incorrect data or unexpected errors, every integration that calls that endpoint is broken — potentially thousands of production applications that cannot self-heal.
API bug reports also require more precise technical detail to be actionable. "The API returns an error sometimes" is not a bug report. "POST /v2/webhooks returns a 500 status code when the payload exceeds 64KB, with the error body {"code": "INTERNAL_ERROR", "message": null} instead of the documented {"code": "PAYLOAD_TOO_LARGE", "message": "..."}" is. The difference between these two determines whether an engineer can reproduce and fix the bug in an hour or spend two days trying to reproduce it.
Breaking change assessment is unique to API bugs. If a bug has been present for a long time, some clients may have built their integration logic around the "buggy" behavior — relying on that specific error code, that specific response schema, or that specific timing. Fixing the bug then becomes a breaking change for those clients. This assessment must be done before every API fix, not as an afterthought.
Template sections
5 sections covering the complete bug report workflow.
Bug summary and severity classification
Start with a one-sentence summary that includes the endpoint, the behavior, and the observed vs. expected outcome. Classify severity immediately: P0 (API is down or data is corrupted for all consumers), P1 (significant percentage of requests failing or incorrect), P2 (edge case with workaround), P3 (cosmetic or documentation issue). Severity determines response time.
Summary: POST /v2/messages returns HTTP 200 with an empty `id` field when the message content contains emoji characters, instead of returning the created message ID. Severity: P1 — affects all integrations that send messages with emoji. Integrations that depend on the returned `id` for tracking are broken. Workaround: strip emoji before sending (unacceptable for production use).
Tips
- Always include the full endpoint path including version prefix — /v1/users is a completely different contract than /v2/users
- Rate the severity against impact, not complexity of the fix — a simple fix that breaks 1,000 integrations is P0
- For P0 and P1 bugs: page the on-call engineer and start an incident channel immediately — do not wait for the bug to be triaged
Exact reproduction with cURL
Provide the exact cURL command that reproduces the bug. This is the single most important field in an API bug report. Include all required headers, the request body, and the authentication header (redacted but with the correct key name). Include the exact response: status code, headers, and body. The person reading this report must be able to run the command and reproduce the bug in under two minutes.
``` curl -X POST https://api.example.com/v2/messages \ -H "Authorization: Bearer [REDACTED — your API key]" \ -H "Content-Type: application/json" \ -d '{"to": "user_123", "content": "Meeting at 3pm! 🎉"}' ``` Expected response (per API documentation): ```json {"id": "msg_abc123", "status": "sent", "created_at": "2025-03-15T10:30:00Z"} ``` Actual response: ```json {"id": "", "status": "sent", "created_at": "2025-03-15T10:30:00Z"} ``` HTTP status: 200 (should be 200 — but id field is empty)
Tips
- Redact API keys with [REDACTED] but keep all other header and parameter names visible — the structure is diagnostic information
- Include both the expected response (from the API docs) and the actual response — this immediately confirms whether the documented contract is being violated
- For errors that occur intermittently: include multiple cURL runs with their responses and timestamps to establish the failure rate
SDK and client context
Many API bugs are SDK-specific rather than underlying API bugs. Document the SDK language and version, the HTTP client library, and any relevant configuration. If the same request works via direct cURL but fails via the SDK, the bug may be in the SDK request construction, not the API itself.
SDK context: - SDK: Node.js @company/api-sdk v3.2.1 - HTTP client: axios 1.4.0 - Node.js version: 18.17.0 - Platform: Ubuntu 22.04 (AWS EC2 t3.medium) - SDK configuration: baseURL https://api.example.com/v2, timeout 30000ms, retries: 0 Direct cURL test: Reproduces the bug SDK test: Also reproduces the bug → Confirmed as API-level bug, not SDK-specific
Tips
- Always test with direct cURL in addition to the SDK — it tells you whether the bug is in the SDK or the API
- Include the SDK version number precisely — bugs are often fixed in minor versions and the reporter might be on an outdated SDK
- For bugs that only reproduce via SDK (not cURL): the SDK is likely transforming the request in a way that triggers the bug — inspect the actual HTTP request sent by the SDK
Breaking change assessment
Before fixing any API bug, determine whether the "buggy" behavior has become de-facto behavior that integrations depend on. If clients have been integrating with the buggy behavior for months, fixing it may be a breaking change. The assessment determines whether the fix requires a versioned migration or can be applied immediately.
Breaking change assessment: Question: Do any existing integrations depend on the empty `id` field behavior? Analysis: Queried API logs for the last 90 days. The endpoint has been called 2.3M times. Of responses with emoji content (approximately 8% of calls), integrations that check the `id` field returned to track message delivery number approximately 15,000 unique customers. Risk: If we fix the `id` field to return correctly, integrations that currently work around the empty `id` by using alternative tracking methods will not be broken — they will just have a more correct `id` to use. Conclusion: NOT a breaking change. The fix moves behavior from incorrect to correct per the documented contract. No versioning required. Recommend deploying with standard deployment process.
Tips
- Query your API logs to estimate what percentage of real-world calls are affected — this data is essential for prioritization and for assessing breaking change risk
- When uncertain whether behavior is relied upon: publish a deprecation notice for the buggy behavior 30 days before fixing it, and monitor for customer feedback
- Document your breaking change decision in the bug report so it can be referenced if a customer complains after the fix ships
Customer impact and escalation
Quantify the customer impact using API logs: how many unique API consumers are affected, what is the error rate, which specific customers are experiencing the issue, and what is the business impact (integrations broken, data corrupted, SLA violated). For P0 and P1 bugs, this analysis determines whether an emergency fix and customer communication are required.
Customer impact analysis (pulled from API logs, 2025-03-15): - Total calls to POST /v2/messages in last 24 hours: 847,000 - Calls with emoji content: 67,000 (7.9%) - Calls returning empty `id`: 67,000 (100% of emoji-content calls) - Unique API consumers affected: 1,847 customers - Enterprise customers affected: 23 (accounts with dedicated CSMs) - SLA impact: 3 enterprise customers have API reliability SLAs — empty `id` could be argued as SLA breach Escalation: Notify CSM team immediately for 23 enterprise customers. Prepare status page incident. Target fix: within 4 hours.
Tips
- Pull impact analysis from logs before escalating — "we do not know how many customers are affected" is the most frustrating response to a P0/P1 bug
- For enterprise customers with CSMs: notify the CSM team before the customer discovers and reports the issue — proactive outreach turns an incident into a trust-builder
- Status page policy: all P0 bugs require a status page incident within 15 minutes of confirmed diagnosis
Copy-paste template
## API Bug Report **ID:** [JIRA-XXX or GitHub #XXX] **Reported by:** [Name] | **Date:** [Date] | **Severity:** [P0 / P1 / P2 / P3] **Status:** [New / Confirmed / In Progress / Fixed / Closed] --- ### Summary [One sentence: endpoint + what it does wrong + what it should do instead] **Endpoint:** `[HTTP METHOD] [/api/version/path]` **Affects:** [All requests / % of requests / Specific conditions] --- ### Reproduction **cURL command:** ```bash curl -X [METHOD] [URL] \ -H "Authorization: Bearer [REDACTED]" \ -H "Content-Type: application/json" \ -d '[REQUEST BODY — include the exact payload that triggers the bug]' ``` **Expected response** *(per API documentation)*: ```json [Expected JSON response] ``` **Actual response:** ```json [Actual JSON response] ``` **HTTP status code:** [Expected: XXX | Actual: XXX] **Reproduction rate:** [Always / ~X% of the time / Only under specific conditions: describe] --- ### SDK and Client Context - SDK: [Language + SDK name + version — e.g., "Node.js @company/sdk v3.2.1"] - HTTP client: [e.g., "axios 1.4.0"] - Runtime: [e.g., "Node.js 18.17.0 / Python 3.11"] - Platform: [e.g., "AWS Lambda / Heroku / Ubuntu 22.04"] - Reproduces via direct cURL: [Yes / No] - Reproduces via SDK: [Yes / No] - Conclusion: [API-level bug / SDK-level bug] --- ### Breaking Change Assessment - **How long has buggy behavior existed?** [Date first observed or estimated] - **Do integrations depend on the buggy behavior?** [Evidence from log analysis] - **Fix impact on existing integrations:** [Breaking / Non-breaking — reasoning] - **If breaking: migration path:** [Description of migration clients must make] - **Versioning required:** [Yes — new API version / No — fix in place] --- ### Customer Impact - **Affected API calls (24h):** [X calls | Y% of total] - **Unique consumers affected:** [N customers] - **Enterprise customers affected:** [N — names if known] - **SLA implications:** [Yes — describe / No] - **Data integrity risk:** [Data corrupted / Data lost / No data impact] --- ### Escalation - **Status page incident required:** [Yes / No] - **Customer communication required:** [Yes — by: [Date] / No] - **CSM team notification:** [Sent / Not required] - **Target fix timeline:** [Hours / Days / Next sprint]
Frequently asked questions
Generate instead of filling in templates
Connect your tools, and Vantage generates the content using real product data. Free to start.
Free to start. No credit card required.