API Error Report Checklist

API Error Report Checklist helps a developer report an API failure with enough detail to separate authentication, validation, transport, data, and server-side behavior.

Start with the request identity. Record method, endpoint path, query string, content type, API version, environment, and whether the request was sent from browser, CLI, server job, webhook, mobile app, or test runner. Do not include secrets. Replace access tokens, cookies, and private IDs with placeholders that preserve the shape of the request.

Next record the response. Status code alone is not enough. Capture response body, error code, message, headers that affect behavior, request id or trace id, and whether the response is JSON, HTML, empty, or a network-level failure. A 400 with field-level validation is a different class of problem from a 401, a 403, a 409 conflict, a 422 schema error, a 429 rate limit, a 502 gateway failure, or a request that never reaches the server.

Then add a smallest reproducible input. Remove unrelated fields one by one until the failure disappears or the request is minimal. If a file is involved, record file type, size range, encoding, and whether a small synthetic file can reproduce the same behavior. If a webhook is involved, include event type, timestamp pattern, retry count, and idempotency key status. If pagination or sorting is involved, record cursor, limit, sort order, and the expected item position.

Finally add comparison evidence. Did the same request work yesterday? Does it fail for one account role and not another? Does staging differ from production? Does curl fail the same way as the UI? Does a different region, browser, or network change the result? These comparisons often identify whether the issue is client-side, permission-related, data-specific, or systemic.

A strong API error report avoids speculation until the evidence is laid out. It says what was sent, what came back, what changed, and what minimal case still fails.

API Error Report Checklist

// COMMENTS

ON THIS PAGE