Production-only API 500: what to capture before changing backend code

A production-only API 500 should start with a capture checklist, not an immediate rewrite, because the failing condition may be environment, data shape, headers, or runtime behavior.

The first capture is the request shape. Record method, path, query string, content type, auth state, user role, payload size, and the exact timestamp. Do not rely on a screenshot of a red error banner. A backend 500 needs enough detail for another developer to replay the request safely or compare it with a working request. If the browser sends a preflight request, capture that separately from the real request.

The second capture is the response and trace. Record status code, response body if safe, request id, server log line, upstream service name, and whether the same request works in a preview or local environment. The point is to identify the first component that knew the request failed. If the edge layer returns the 500 before application code runs, editing handler logic will not fix it.

The third capture is the data and configuration boundary. Check whether the failing account, region, feature flag, file size, database row, or missing optional field exists only in production. Many production-only failures are not mysterious; they are simply caused by a data case that test fixtures never included.

A good note ends with the smallest safe reproduction: same endpoint, same method, same relevant headers, same permission level, and a redacted payload that still triggers the failure. If that cannot be built yet, the next action is more capture, not guessing.

Use this checklist when the phrase “works locally” appears in the incident thread. It keeps the team from changing code before proving which layer is different.

Production-only API 500: what to capture before changing backend code

// COMMENTS

ON THIS PAGE