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 }?
}
