Some errors require further explanation beyond a standard HTTP status code. For example, the API reports an unsuccessful resource state update or action with a fault
representation in the response entity body. The fault contains a reason
and detail
strings. Clients must accomodate failed requests via extracting the fault
or the expected resource representation depending on the response status code. Such cases are clearly indicated in the individual resource documentation.
PUT /api/collection/resource_id HTTP/1.1
Accept: application/xml
Content-Type: application/xml
<resource>
<id>id-update-test</id>
</resource>
HTTP/1.1 409 Conflict
Content-Type: application/xml
<fault>
<reason>Broken immutability constraint</reason>
<detail>Attempt to set immutable field: id</detail>
</fault>