Subject: Re: Status codes

From: Nicolas Popp <[email-masked]>
Date: Wed, 14 Jun 2000 17:29:54 -0700

Here is the simplified proposal for status codes:

The top level codes denote levels of severity of the status:

   o  1.X.X Informational

      *  The information conveyed by the code has no bearing or
         indication of the success or failure of any request. It is
         strictly for informational purposes only.

   o  2.X.X Success

      *  The request was processed and results were returned. In most
         cases this status class won't be sent since actual results
         themselves denote success. In other cases results were
         returned but some information needs to be returned to the
         client.

   o  3.X.X Partial Success

      *  The request was processed and results were returned. In this
         case though, some values sent with the request were either
         invalid or ignored but in a way that the server still
         considers the response to be a successful one and not
         indicative of any true error condition.

   o  4.X.X Transient Failure

      *  The request was valid as sent, but some temporary event
         prevents the successful completion of the request and/or
         sending of the results. Sending in the future may be possible.

   o  5.X.X Permanent Failure

      *  A permanent failure is one which is not likely to be resolved
         by re-sending the request in its current form. Some change to
         the request or the destination must be made for successful
         request.

   The second level codes denote the subject of the status messages.
   This value applies to each of the three classifications.  The
   subject sub-code, if recognized, must be reported even if the
   additional detail provided by the detail sub-code is not recognized.
   The enumerated values for the subject sub-code are:

   o  X.0.X Other or Undefined Status

      *  No specific information is available about what subject class
         this message belongs to

   o  X.1.X Query Related

      *  Any status related to some specific way in which the query was
         encoded. This includes any status related to the query
         properties and their values and any status related to actual
         XML encoding of the request.

   o  X.2.X Service Related

      *  Any status related to the service in which this server is
         cooperating in providing.  This includes any status related to
         a particular server or dataset.

   Appendix B contains a list of all predefined status codes

---------------------------------------------------------------------

APPENDIX B:

B.1 Level 1 (Informative) Codes

   1.0.0 -- Undefined Information
      This code is used for any non-categorizable and informative
      message. If, for example, the server wanted to tell the client
      that the systems administrator's cat has blue hair, then this
      code would be the appropriate place for this information.
   1.1.0 -- Query related information
      This code is used for any informative information concerning the
      query that the client sent. For example, "The query you sent was
      rather interesting!". This code is used for any informative
      message pertaining to a particular property within the query as
      well as to the XML sent by the client.
   1.2.0 -- Service related information
      This message concerns the service in the general sense and
      includes informative messages about a specific server and
      dataset.

B.2 Level 2 (Success) Codes

   2.0.0 -- Something undefined succeeded
      There was success but the situation that this message concerns is
      undefined.
   2.0.0 -- Query succeeded
      The query succeeded. This message MUST be returned when there
      were no results that matched the query. I.e. the query was
      successfully handled and the correct set of results contained no
      resources or referrals. The lack of results is not an error but a
      successful statement about the common-name.

   NOTE: The apparent lack of 2.X.X level codes is caused by success
   usually being indicated not by a status message but by the server
   returning only the objects that the client requested.

B.3 Level 3 (Partial Success) Codes

   3.0.0 -- Something undefined was only partially successful
      Some request by the client was only partially successful. The
      exact situation or cause of that partial failure is not defined.
   3.1.0 -- The query was only partially successful.
   3.1.1 - The query contained invalid or unsupported properties
        The query contained invalid or unsupported property names,
      types or values. The invalid properties were ignored and the
      query processed.
   3.1.2 - The XML was well formed but invalid
        The XML sent by the client was well formed but invalid.
      Nevertheless, the server tried to interpret the query and
returned some results that may be incomplete.
   3.2.0 -- The server caused a partially successful event
      Due to some internal server error, the results returned were
      incomplete.
   3.2.1 -- Some referral server was unavailable
      This status message is used to denote that one or more of the
      referral services that are normally queried were unavailable.
      Results were generated but they may not be representative of a
      complete answer.

B.4 Level 4 (Persistent Transient Failure) Codes

   4.0.0 -- Something undefined caused a persistent transient failure
   4.1.0 -- An error in the query caused a persistent transient failure
   4.2.0 -- A service error caused a persistent transient failure
   4.2.1 -- This server is too busy
      Due to resource constraints, this particular server was too busy
      to handle the query. It is very appropriate to attempt to send
      the query to other servers who are cooperating in providing the
      service.
   4.2.2 - This server is in maintenance.
This server is now in maintenance mode. Try another server from
this service or try again at a later time.

B.5 Level 5 (Permanent Failures) Codes

   5.0.0 -- Something undefined caused a permanent failure
   5.1.0 -- An error in the query caused a permanent failure
   5.2.0 -- The service had a permanent failure
   5.2.1 -- This service is no longer available.
      This service has decided to no longer make itself available.
   5.2.2 -- This server had a permanent failure.
        This server has permanently failed. Try another server from this
      service.
   5.2.3 -- This server is no longer available
      This server has permanently failed or is no longer part of this
      service. Any subsequent requests should be directed at another
      server.

-Nico

---

From: Michael Mealling <[email-masked]>
Date: Fri, 16 Jun 2000 08:33:03 -0400

> Here is the simplified proposal for status codes:

A few comments....

> <snip>

Essentially everything stays the same except that anything not
related to the service is put into one section....

> <no real changes>
> <no real changes>

This one needs a correlating error in 400 level codes....

> this service or try again at a later time.

I'd add this:

    4.2.3 -- The XML was invalid and nothing could be done.

This is essentially your standard syntax error message...

>    5.1.0 -- An error in the query caused a permanent failure

Umm....This one doesn't make sense. Are you saying that a query
caused the server to never be available ever again?

This level of severity basically says that the state
that the status message says the server is in is permanent...
E.g. is there was a failure the client can assume that it can
remove this Server from the list of valid Servers for this Service...

--
--------------------------------------------------------------------------------
Michael Mealling        |      Vote Libertarian!       | www.rwhois.net/michael
Sr. Research Engineer   |   www.ga.lp.org/gwinnett     | ICQ#:         14198821
Network Solutions       |          www.lp.org          |  [email-masked]