How to Report API Bugs: Template, Examples and Severity

Finding an API bug is half the job. The other half is reporting it so clearly that a developer can reproduce it in one minute, understand the impact and fix the right thing. A vague ticket like “Order API not working” bounces back and forth for days; a precise one with a cURL command gets fixed the same day. In this lesson you’ll learn the API bug report template that developers love, how to judge severity and priority, and see real examples, including genuine issues found during this course.

Why API Bug Reports Are Different

UI bugs can be shown with a screenshot. API bugs live in requests and responses that nobody can see unless you capture them. That means:

• The exact request matters: one header or one field type changes everything.
• The exact response (status, headers, body) is the evidence.
• Backend logs are searchable by request id and timestamp, so include them.
• The same API serves web, Android, iOS and partners, so state which client or whether it’s reproducible directly.

The API Bug Report Template

Writing a Great Title

A strong title lets a lead triage the bug without opening it.

Capturing the Request Correctly

• Postman: Code (</>) → cURL. Make sure variables are resolved (check the Console).
• Browser: DevTools → Network → right-click → Copy as cURL. Or save a HAR file for multi-request issues.
• Playwright: attach request and response to the test report, or use the trace viewer.
• Mobile: proxy the app through Charles, Proxyman or mitmproxy on a test device.

Example 1: Validation Bug (Full Report)

Title:        POST /objects returns 500 when "ttl" is a JSON array instead of 422

Environment:  QA - https://qa.shop.example/api/v1, build 2026.11.3, 12-Nov-2026 15:20 IST
Preconditions: none (endpoint is public)

Request:
curl -i -X POST "https://qa.shop.example/api/v1/objects" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bag","ttl":[60]}'

Actual:
HTTP/1.1 500 Internal Server Error
X-Request-Id: 9f2c1d7e
{"error":"Unhandled exception"}

Expected:
HTTP/1.1 422 with error.details[0].field = "ttl"
(OpenAPI: NewObject.ttl is integer 10-1800; API guidelines section 4: invalid input -> 422)

Reproducibility: 5/5. Same result for ttl = {}, true.
Severity: Medium (unhandled exception; no data impact)   Priority: P2
Impact: Any client sending a wrong type gets a 500; error monitoring is flooded.
Notes:  ttl = "60" (string) correctly returns 422, so only non-scalar types fail.

Notice the extra analysis in Notes. It narrows the cause to “non-scalar types” and saves the developer time.

Example 2: Security Bug (BOLA)

Title:        GET /orders/{id} returns other customers' orders (BOLA / IDOR)

Environment:  Staging, build 2026.11.2
Preconditions: Customer A (qa_cust_a) and Customer B (qa_cust_b), both role=customer.
               Order 70412 belongs to B.

Request (as A):
curl -i "https://staging.shop.example/api/v1/orders/70412" -H "Authorization: Bearer <TOKEN_CUSTOMER_A>"

Actual:   200 OK with B's name, phone, address and items.
Expected: 404 (or 403) and no data. (Security requirement SEC-12: users access only their own orders.)

Reproducibility: Always. Order ids are sequential, so any order can be read.
Severity: Critical   Priority: P1 (blocker for release)
Impact:   Personal data of all customers exposed to any logged-in user. Data protection risk.
Notes:    PATCH /orders/70412 as A returns 403 correctly, so only the read path lacks the ownership check.

Security bugs often go into a restricted ticket or a separate security queue. Follow your company’s disclosure process.

Example 3: Real Findings From This Course

While writing these lessons we tested real public services. Two genuine, reportable observations:

Stack trace in a public SOAP service

Title:   Divide with intB=0 returns SOAP Fault exposing stack trace and server file path
Service: http://www.dneonline.com/calculator.asmx (public demo calculator)
Actual:  HTTP 500, faultcode soap:Server, faultstring contains
         "System.OverflowException ... at Calculator.Divide(Int32 intA, Int32 intB) in G:\PleskVhosts\...\Calculator.asmx:line 19"
         plus header X-AspNet-Version: 2.0.50727
Expected: soap:Client fault with a safe message such as "intB must not be 0"; no stack trace, paths or version headers.
Severity: Medium (information disclosure, OWASP API8)

Inconsistent error format for unknown versions

The SQA Tools practice API returns its own error shape {"error":{"status","code","message"}} everywhere, except for unknown routes such as a wrong version, where the underlying framework answers with a different shape:

curl -i \
  "https://sqatools.in/wp-json/sqa-api/v1/../v9/users"

GET https://sqatools.in/wp-json/sqa-api/v9/users
Actual:   404 {"code":"rest_no_route","message":"No route was found ...","data":{"status":404}}
Expected: 404 in the documented format {"error":{"status":404,"code":"not_found","message":"..."}}
Severity: Low   Priority: P3
Impact:   Clients that parse error.code break on this path.

Low severity, but exactly the kind of consistency issue a careful tester reports.

Severity vs Priority

Before You Click “Create”: Self-Check

1. Did I reproduce it at least twice, ideally with a fresh token and fresh data?
2. Is it really a bug? Check the spec, the story and recent changes. If the spec is unclear, raise a question rather than a bug.
3. Is it a duplicate? Search existing tickets by endpoint.
4. Did I isolate the minimum request that fails (remove unrelated fields)?
5. Did I include request id/timestamp so logs can be found?
6. Did I remove secrets and personal data?
7. Is the expected result backed by a reference, not my opinion?

Automation Failures vs Real Bugs

When an automated API test fails, triage before reporting:

• Product bug: the API changed behaviour against the spec. Report with the request from the test report.
• Test bug: wrong expectation, hardcoded data, order dependency. Fix the test.
• Environment issue: service down, expired test credentials, data reset. Notify the environment owner, don’t log a product bug.
• Flaky: passes on rerun. Investigate timing, shared data and rate limits; don’t just add retries.

Playwright makes evidence easy: attach the response to the report on failure.

test('POST /objects returns 201', async ({ request }, testInfo) => {
  const res = await request.post(`${BASE}/objects`, { data: { name: 'Bag', ttl: 60 } });
  if (res.status() !== 201) {
    await testInfo.attach('response', {
      body: JSON.stringify({ status: res.status(), headers: res.headers(), body: await res.text() }, null, 2),
      contentType: 'application/json',
    });
  }
  expect(res.status()).toBe(201);
});

Communicating With Developers

• Be factual: “returns 500” not “the API is broken”.
• Offer analysis, not blame: “fails only for non-scalar ttl values” helps more than “validation is missing everywhere”.
• For critical bugs, message the developer or lead directly as well as filing the ticket.
• Retest promptly when fixed, on the same data plus related cases (fixes often break neighbours).
• Close the loop: add an automated regression test so it can’t come back.

Interview Questions: API Bug Reporting