The Spec is unclear about what errors should look like.

[n3wscott]

I think if the spec intends Error to be optionally returned for any error case it needs to be reworked. This is the language:

Service Brokers can include a user-facing message in the description field;

There is no spec language in that sentence, like MAY, and it is unclear is the broker author is allowed to return the description field for any responses or just for responses that call out they return errors.

The confusion happens when the spec says The expected response body is {}. This is redundant and unclear.

We should simplify errors to say they MAY always send error and description for all errors and remove the special cases for special errors.

[mattmcneeney]

I agree @n3wscott - anytime an API error occurs, brokers should be able to return the same error object. This is much more straightforward for platforms to understand.

I know we have the openapi changes for this in #389. We should make a sweeping change to spec.md too to clarify this if everyone agrees this is sensible.

[fmui]

This is related to #375.

[mattmcneeney]

Good spot @fmui. Although #375 looks like an extension to the spec (adding error codes) whereas this issue is regarding removing ambiguity.

[mattmcneeney]

This is going to be resolved by #409 so I'm closing this issue.