The spec mandating its as a single string isn’t that crazy. It’s good to have a consistent response format so a basic deserializer can deserialize any error response object and get something out.

If you have different providers. One that returns error: { code: string } and another does something else, you end up with the same problem this post talks about-- Inconsistency.

As far as I can tell, the spec doesn’t limit you to just the one field and you can add other optional fields to the top level to the response that the caller can optionally decide to handle. But if you know there’s going to be a field called error that is a string. You always get at least something out of that to present.

It just goes to show the small parts of API design matter just as much as the big parts. I’ve worked with a lot of engineers who are so eager to draw big boxes and arrow architectural diagrams, but then just rush the details because that’s not important.