[grandalf]

> I generally prefer those that use HTTP status codes + error payload

I have less of a a problem with that approach, but I do think that it can be confusing if the consumer reads too much into the meaning of the HTTP status codes. In general, sometimes the HTTP status code adds useful information but ideally the application specific error modes would cover all non-transport error conditions nicely.

> There are no unexpected status codes if your API is fully documented.

Totally agree with this, documentation is the most important thing.