Abstract
Introduce a new Error Report Document to express human readable descriptions of failure conditions.
Status
Withdrawn
Rationale
Proposal
4.6. Error Reports When an error occurs and is reported to the client, the HTTP response payload MUST contain an Error Report Document. Error Report Documents provide a human readable description of the error condition being reported by the server. An example Error Report HTTP/1.1 401 Unauthorized WWW-Authenticate: BASIC realm="Whomever" Content-Type: application/atomerr+xml Content-Length: nnn <app:error> <app:reason>Invalid User ID and Password</app:reason> <app:description>This Atom Collection allows access only to authorized users.</app:description> <app:recommendation>Please supply a valid user ID and Password.</app:recommendation> <app:more href="http://www.example.com/errors/description/authentication" /> </app:error> Error Report Documents MUST NOT be used for automated determination of error conditions. Clients MUST refer to the HTTP status code in order to determine the type of failure that has occurred. 4.6.1 The 'app:error' Element The 'app:error' element represents an Atom Error Report. appError = element app:error { appCommonAttributes, (appReason*, & appDescription*, & appRecommendation*, & appMore { uri }*) } * app:error elements MUST contain at least one app:reason element. * app:error elements MUST NOT contain more than one app:reason having the same xml:lang value. * app:error elements MAY contain any number of app:description elements. * app:error elements MUST NOT contain more than one app:description having the same xml:lang value. * app:error elements MAY contain any number of app:recommendation elements. * app:error elements MUST NOT contain more than one app:recommendation having the same xml:lang value. * app:error elements MAY contain any number of app:more elements. * app:error elements MUST NOT contain more than one app:more element having the same combination of type and hreflang attributes. 4.6.2 The 'app:reason' Element The 'app:reason' element provides a short, plain text, human readable summary of why the error occurred. The value of of app:reason MUST NOT contain escaped HTML or XML markup. appReason = element app:reason { appCommonAttributes, text } 4.6.3 The 'app:description' Element The 'app:description' element provides an extended, plain text, human readable description of the error. The value of of app:description MUST NOT contain escaped HTML or XML markup. appDescription = element app:description { appCommonAttributes, text } 4.6.4 The 'app:recommendation' Element The 'app:recommendation' element provides a plain text, human readable description of actions the client should take to correct the problem that led to the error condition. The value of of app:recommendation MUST NOT contain escaped HTML or XML markup. appRecommendation = element app:recommendation { appCommonAttributes, text } 4.6.5 the 'app:more' Element The 'app:more' element provides a URI where additional information about the error can be found. appMore = element app:more { appCommonAttributes, attribute href { atomURI }, attribute type { media-type }?, attribute hreflang { language-tag }?, attribute title { text }? }