Response Envelope

Two shapes, and the field to branch on.

Every endpoint returns one of these two shapes. Check success first, always — an HTTP 200 with success: false is a valid failure, and a failed transaction is not the same thing as a failed request.

{ "success": true,  "data": { ... } }

{ "success": false, "error": { "code": "ERR_CODE", "message": "human readable" } }

The code is stable and safe to branch on; the message is written for a human and may be reworded at any time. Never match on the message.