Add text around what brokers should do upon failures

Provide more guidance for what should happen when things go wrong
so we can ensure a more consistent semantics and interop.

This should only be reviewed after #353

Signed-off-by: Doug Davis <[email protected]>

spec.md

@@ -720,7 +720,9 @@ For success responses, the following fields are valid.
 
 If the successful response includes a `state` of `failed` then the Platform
 MUST send a deprovision request to the Service Broker to prevent an orphan
-being created on the Service Broker.
+being created on the Service Broker.  However, while the Platform will attempt
+to send a deprovision request, Service Brokers MAY automatically delete
+any resources associated with the failed bind request on their own.
 
 ### Polling Interval and Duration
 
@@ -823,7 +825,9 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc
 
 Responses with any other status code will be interpreted as a failure and a
 deprovision request MUST be sent to the Service Broker to prevent an orphan
-being created on the Service Broker.
+being created on the Service Broker. However, while the platform will attempt
+to send a deprovision request, Service Brokers MAY automatically delete
+any resources associated with the failed provisioning request on their own.
 
 Service Brokers can include a user-facing message in the `description` field;
 for details see [Service Broker Errors](#service-broker-errors).
@@ -962,7 +966,12 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc
 | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. |
 | 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the Service Instance (e.g. Service Instance utilization is over the quota of the requested plan). Service Brokers SHOULD include a user-facing message in the body; for details see [Service Broker Errors](#service-broker-errors). Additionally, a `422 Unprocessable Entity` can also be returned if the Service Broker only supports asynchronous update for the requested plan and the request did not include `?accepts_incomplete=true`; in this case the expected response body is: `{ "error": "AsyncRequired", "description": "This Service Plan requires client support for asynchronous service operations." }` (see [Service Broker Errors](#service-broker-errors). |
 
-Responses with any other status code will be interpreted as a failure. Service Brokers can include a user-facing message in the `description` field; for details see [Service Broker Errors](#service-broker-errors).
+Responses with any other status code will be interpreted as a failure and
+the Service Broker MUST NOT apply any of the requested changes to the
+service instance.
+
+Service brokers can include a user-facing message in the `description` field;
+for details see [Service Broker Errors](#service-broker-errors).
 
 #### Body
 
@@ -1165,9 +1174,12 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc
 
 Responses with any other status code will be interpreted as a failure and an
 unbind request MUST be sent to the Service Broker to prevent an orphan being
-created on the Service Broker. Service Brokers can include a user-facing
-message in the `description` field; for details see [Service Broker
-Errors](#service-broker-errors).
+created on the Service Broker. However, while the platform will attempt
+to send an unbind request, Service Brokers MAY automatically delete
+any resources associated with the failed bind request on their own.
+
+Service brokers can include a user-facing message in the `description` field;
+for details see [Service Broker Errors](#service-broker-errors).
 
 #### Body
 
@@ -1299,10 +1311,10 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan
 | 410 Gone | MUST be returned if the binding does not exist. The expected response body is `{}`. |
 
 Responses with any other status code will be interpreted as a failure and the
-Platform MUST continue to remember the Service Binding. Service Brokers can
-include a user-facing message in the `description` field; for details see
-[Service Broker Errors](#service-broker-errors).
+Platform MUST continue to remember the Service Binding.
 
+Service brokers can include a user-facing message in the `description` field;
+for details see [Service Broker Errors](#service-broker-errors).
 
 #### Body
 
@@ -1374,9 +1386,10 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan
 | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous deprovisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The expected response body is: `{ "error": "AsyncRequired", "description": "This Service Plan requires client support for asynchronous service operations." }`, as described below (see [Service Broker Errors](#service-broker-errors). |
 
 Responses with any other status code will be interpreted as a failure and the
-Platform MUST remember the Service Instance. Service Brokers can include a
-user-facing message in the `description` field; for details see [Service Broker
-Errors](#service-broker-errors).
+Platform MUST remember the Service Instance.
+
+Service Brokers can include a user-facing message in the `description` field;
+for details see [Service Broker Errors](#service-broker-errors).
 
 #### Body