How to write an API error report that someone can reproduce

A good API error report lets another developer reproduce the failure without private tokens or guesswork. This guide shows what to include: endpoint, method, sanitized request, response status, error body, timing, and the smallest reproduction step.

## Name the request precisely
Start with method, endpoint, and environment. "POST /api/v1/orders in staging" is better than "order API is broken." If the endpoint has query parameters, include the full path with safe values. If the request depends on a feature flag or tenant setting, name the flag or setting without exposing secrets.

## Separate request shape from private data
Include headers only when they matter. Redact Authorization, cookies, session IDs, and customer identifiers. Keep content type, idempotency key presence, API version, and correlation ID if the system uses them. For the JSON body, replace private values with realistic placeholders while preserving field names, nulls, arrays, and missing fields.

## Capture the response
Write down the status code, error code, response body, and response time if available. A 400, 401, 409, and 500 require different owners. If the response contains a trace ID, include it. If the UI swallowed the error, capture the underlying network response rather than only the toast message.

## Add reproduction steps
A reproducible report should include the smallest sequence: create fixture, send request, observe response. If the failure only happens after a previous request, include that dependency. If it only happens with one account or region, say that clearly and avoid copying private account details.

## Add expected behavior
Expected behavior should be concrete. "Should work" is not enough. Write "returns 201 with order_id" or "returns 409 with duplicate-key message". This helps the receiver decide whether the bug is in the API, client, validation, or documentation.

## Template
- Method and endpoint
- Environment
- Sanitized request
- Actual status and body
- Expected status and body
- Trace or correlation ID
- Reproduction steps
- First time observed

This format reduces back-and-forth and prevents sensitive data from becoming part of the debugging record.

How to write an API error report that someone can reproduce

// COMMENTS

ON THIS PAGE