mcclowes/api-design
Use when designing, reviewing, or implementing HTTP APIs — error and warning handling, resource state and lifecycle, read-endpoint structure, pagination, and authentication. Triggers on error responses and formats, response envelopes, webhook payloads, how an endpoint should fail; modelling a resource lifecycle (status fields, state machines, webhook event names, enum vs parseable string); structuring read endpoints (screen-shaped/BFF vs canonical resource, aggregation, cursor vs offset pagination); and auth design (security schemes, API keys vs bearer tokens, stepped-up tokens). Apply whenever an API surfaces a failure, state change, view of data, or auth requirement to a client.
96
90%
Does it follow best practices?
Impact
99%
1.70xAverage score across 8 eval scenarios
Passed
No known issues
task.mdevals/scenario-3/
Design a payouts endpoint error response
I'm building a POST /api/v1/payouts endpoint in our Next.js app. It can fail in a few ways: the user's connected bank token has expired, the requested amount exceeds their daily payout limit, and sometimes our payment provider (a vendor called Sequra) rejects it with its own error code. Design the JSON error response body the API should return for these cases.