API 500 Debug Note Template

# API 500 Debug Note Template

A 500 response is not a diagnosis. It only says the server failed to complete the request. A useful debug note should capture the request shape, response body, auth context, expected status, and the smallest known reproduction. Without that structure, a 500 report becomes “it broke” plus a timestamp.

## 1. Request shape
Record method, path, content type, auth mode, and minimal body. Do not paste secrets. If the body is large, reduce it to the fields required to reproduce. If the endpoint behaves differently with an empty body, invalid body, and valid body, note that distinction.

## 2. Response shape
Capture status, response body, headers that affect behavior, and whether the body is empty. An empty 500 response is itself useful evidence because it may mean the failure happened before the JSON error wrapper was reached.

## 3. Environment
Write production/staging/local, user role, account state, and whether the same request works for another account. Many 500s are not general outages; they are data-shape or permission-edge failures.

## 4. Reproduction boundary
Use Reproduced / Not Reproduced / Unknown. Example: reproduced with account A on endpoint X; not reproduced with account B; unknown whether invited users behave differently. This prevents overclaiming.

## Example
Method: POST. Path: /api/v1/items/123/join. Body: {}. Auth: normal user token. Expected: 200 or 409. Actual: 500 empty body. Reproduced with three non-owner accounts. Not reproduced: not yet tested with owner.

The goal is not to solve the bug in the note. The goal is to make the next engineer start one step past the obvious checks.

API 500 Debug Note Template

// COMMENTS

ON THIS PAGE