One error envelope across every provider
Normalising upstream failures is unglamorous work. It is also the single thing developers thank us for most.
Every API fails differently. One returns 200 with an error field. Another returns 500 for a validation problem. A third returns a bare string.
The cost of that variety
Handling it is the least interesting code in your codebase, and it is duplicated per vendor. Consolidating four providers behind us removed roughly four hundred lines of vendor-specific error handling from one customer's application.
The shape
Every response carries a success boolean. Every failure carries a stable machine-readable code, a message written for a human, and a link to the documentation for that code. Status codes mean what the specification says they mean.
Where it is hard
Some upstreams genuinely cannot distinguish between a bad request and an outage. We map those to a single code and say so in the reference, rather than guessing and being confidently wrong.