UserPreferences

PaceErrorReports


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

Impacts

Notes


CategoryProposals