Subject: IPP> MOD - Status codes

From: [email-masked]
Date: Tue, 22 Apr 1997 10:22:50 -0500

Attached is a proposal for status code defintions.  I
  borrowed the design approach and applicable text from the
  HTTP 1.1 RFC (RFC 2068).  If this proposal is incorporated
  into the IPP Model document, maybe we should include an
  acknowledgement to the authors of HTTP 1.1 in the document.

  I reviewed this proposal with Roger deBry and mapped the
  proposal to Roger's most recent white paper on conformance.
  Finally, I mapped the status conditions to scenarios
  explicitly or implicitly defined in the IPP internet drafts
  and used examples to relate the status codes to certain
  scenarios when appropriate.

  Enjoy!

  Keith

  ================= STATUS CODE PROPOSAL =============

  4.3 Status and Message

  The Status element is a 3-digit integer result code of the
  attempt to understand and satisfy the request.  The Message is
  intended to give a short textual description of the Status.  The
  Status is intended for use by automata and the Message is
  intended for the human user.  An IPP application (i.e. a browser,
  GUI, print driver or gateway) is not required to examine or
  display the Message.

  The first digit of the Status defines the class of response. The
  last two digits do not have any categorization role. There are 4
  values for the first digit:

     o  0xx: Success - The request was successfully received,
        understood, and accepted

     o  1xx: Client Error - The request contained bad syntax or
        cannot be fulfilled

     o  2xx: Server Error - The IPP Printer failed to fulfill an
        apparently valid request

     o  3xx: Communication Error - An error in communications
        occured during the transmission of a request - the request
        cannot be fulfilled

  The individual values of the numeric status codes defined for
  IPP, and an example set of corresponding Messages, are presented
  below. The messages listed here are only recommended -- they may
  be replaced by local equivalents without affecting the protocol.

     Status   = "000"      ; OK
              | "001"      ; OK Attribute Substitution/
                             Attribute Ignored
              | "100"      ; Bad Request
              | "101"      ; User Authentication Required
              | "102"      ; Payment Required
              | "103"      ; Forbidden Operation
              | "104"      ; Operation Not Allowed
              | "105"      ; Operation Not Authorized
              | "106"      ; URL Not Found
              | "107"      ; URL Gone
              | "108"      ; URL Too Large
              | "109"      ; Attribute Not Implemented/
                             Attribute Value Not Supported
              | "200"      ; Internal Server Error
              | "201"      ; Service Unavailable
              | "202"      ; IPP Version Not Supported
              | "203"      ; Operation Not Implemented
              | "204"      ; Printer Error
              | "300"      ; Communications Error
              | extension-code

     extension-code = 3DIGIT

     Message = *<TEXT, excluding CR, LF>

  IPP status codes are extensible. IPP applications are not
  required to understand the meaning of all registered status
  codes, though such understanding is obviously desirable.
  However, applications shall understand the class of any status
  code, as indicated by the first digit, and treat any unrecognized
  response as being equivalent to the x00 status code of that
  class, with the exception that an unrecognized response shall NOT
  be cached.  For example, if an unrecognized status code of 131 is
  received by the IPP application, it can safely assume that there
  was something wrong with its request and treat the response as if
  it had received a 100 status code. In such cases, IPP
  applications should present to the user the Message returned with
  the response, since that Message is likely to include
  human-readable information which will explain the unusual status.

  4.4 Status Definitions

  Each Status is described below, including a description of which
  operation(s) it can follow and any metainformation required in
  the response.

  4.4.1 Successful 0xx

  This class of status code indicates that the client's request was
  successfully received, understood, and accepted.

  4.4.1.1 000 OK

  The request has succeeded. The information returned with the
  response is dependent on the operation, for example:

     Print                 The Job is submitted for printing and
                           the Job URL is returned in the response;

     Cancel                The Job is cancelled;

     Get-Jobs              The Jobs currently belonging to the
                           Printer are returned in the response;

     Get-Attributes        The values for the attributes specified
                           in the request are returned in the
                           response.

  On a Get-Attributes operation, if an IPP Printer encounters any
  attributes in the request that are not implemented, the Printer
  shall return this status and indicate in the response which
  attributes are not supported by the Printer.

  On a Get-Jobs operation, if an IPP Printer encounters any
  attributes in the request that are not implemented and the values
  (if specified) for Job Owner and Job States are supported by the
  Printer, the Printer shall return this status and indicate in the
  response which attributes are not supported by the Printer.

  An IPP application may examine the attributes in the response
  to determine which attributes are not implemented by the Printer.

  4.4.1.2 001 OK Attribute Substitution/Attribute Ignored

  The operation has succeeded.  On a Print operation, the request
  specifies substitute-as-needed for the best-effort attribute.  In
  response to the Print operation, the IPP Printer substituted a
  value for at least one attribute value that is not supported
  and/or ignored at least one attribute that is not implemented.

  An IPP application may examine the attributes and/or attribute values
  in the response to determine which attributes are not implemented
  and/or which attribute values are not supported by a Printer.

  In practice, an IPP application should avoid this situation by
  querying an IPP object for its valid attributes and values
  before performing an operation on the object.

  4.4.2 Client Error 1xx

  The 1xx class of status code is intended for cases in which the
  client seems to have erred.  IPP applications should display any
  included Message to the end-user.  Unless otherwise noted, these
  status codes apply to all operations.

  4.4.2.1 100 Bad Request

  The request could not be understood by the IPP Printer due to
  malformed syntax.  The IPP application should not repeat the
  request without modifications.

  4.4.2.2 101 User Authentication Required

  The request requires user authentication.

  4.4.2.3 102 Payment Required

  This request requires payment by the end-user to perform the
  Print operation.

  4.4.2.4 103 Forbidden Operation

  The IPP Printer understood the request, but is refusing to fulfill
  it.  Authorization will not help and the request should not be
  repeated.  This status code is commonly used when the IPP Printer
  does not wish to reveal exactly why the request has been refused
  or when no other response is applicable.

  4.4.2.5 104 Operation Not Allowed
  The operation is not allowed for the object identified by the
  URL.  For example, a Print operation is not allowed on a Job
  object specified by a Job URL.

  4.4.2.6 105 Operation Not Authorized

  The request requires that an end-user have access to an object
  and the authorization to perform an operation on the object.  For
  example, an end-user might be authorized to list others' Jobs but
  the end-user is not authorized to cancel others' Jobs.  For
  another example, an end-user might not have access to a Printer
  either because the end-user is not defined in the access control
  list for the Printer or the end-user does not have access to the
  Printer across a firewall.

  4.4.2.7 106 URL Not Found

  The server name in the URL is not found or the server cannot find
  the object specified in the URL. No indication is given of
  whether the condition is temporary or permanent.

  An application should use a Directory Service to return a list of
  valid Printer URLs and use the Get-Jobs operation to return a list
  of valid Job URLs for a Printer so an end-user can select from a
  valid list of URLs.

  4.4.2.8 107 URL Gone

  The requested object is no longer available to the server specified
  in the URL.  This condition should be considered permanent. Clients
  with link editing capabilities should delete references to the URL
  after user approval.  This response is cachable.

  This response is primarily intended to notify the recipient that
  the resource is intentionally unavailable and that the server
  owners desire that remote links to that resource be removed. Such
  an event is common for resources belonging to individuals no
  longer working at a site.

  4.4.2.9 108 URL Too Large
  The server specified in the URL is refusing to service the request
  because the URL is longer than the server is willing to interpret.
  This condition is only likely to occur when an IPP application allows
  an end-user to type an invalid URL for an IPP object and then
  specifies that URL on an operation.  An application should use a
  Directory Service to return a list of valid Printer URLs and use
  the Get-Jobs operation to return a list of valid Job URLs for a
  Printer so an end-user can select from a valid list of URLs.

  4.4.2.10 109 Attribute Not Implemented/Attribute Value Not Supported

  For a Print operation, if the IPP Printer does not implement at
  least one attribute and/or at least one attribute value in the
  request and either the request specifies do-not-substitute for
  the best-effort attribute or the Printer cannot process the
  request correctly, the Printer shall return this status and
  indicate in the response which attributes and/or attribute values
  are not supported by the Printer.
  For example, if an IPP Printer can only support 1 Document per
  Job and the Printer receives multiple documents in a Print
  operation, the Printer shall return this status.  For another
  example, if the Print operation specifies do-not-substitute,
  the request requires A4 paper and that paper size is not
  available on the Printer, the Printer shall return this status.

  For a Get-Jobs operation, if the IPP Printer does not support at
  least one attribute value for Job Owner and/or Job States in
  the request, the Printer shall return this status and indicate
  in the response which attributes and/or attribute values are not
  supported by the Printer.

  An IPP application may examine the attributes and/or attribute values
  in the response to determine which attributes are not implemented
  and/or which attribute values are not supported by a Printer.

  In practice, an IPP application should avoid this situation by
  querying an IPP Printer for its valid attributes and values
  before performing a Print operation on the Printer.

  4.4.3 Server Error 2xx

  Response status codes beginning with the digit "2" indicate cases
  in which the IPP Printer is aware that it has erred or is
  incapable of performing the request.  IPP applications should
  display any included Message to the end-user.  Unless otherwise
  noted, these status codes apply to all operations.
  4.4.3.1 200 Internal Server Error

  The IPP Printer encountered an unexpected condition which
  prevented it from fulfilling the request.

  4.4.3.2 201 Service Unavailable

  The IPP Printer is currently unable to handle the request due to a
  temporary overloading or maintenance of the Printer.  The
  implication is that this is a temporary condition which will be
  alleviated after some delay. If known, the length of the delay
  may be indicated in the Message.  If no delay is given, the IPP
  application should handle the response as it would for a 200
  response.

  4.4.3.3 202 IPP Version Not Supported

  The IPP Printer does not support, or refuses to support, the IPP
  protocol version that was used in the request message. The IPP
  Printer is indicating that it is unable or unwilling to complete
  the request using the same major version as the client other than
  with this error message. The response should contain a Message
  describing why that version is not supported and what other
  versions are supported by that IPP Printer.

  4.4.3.4 203 Operation Not Implemented

  The IPP Printer does not support the functionality required to
  fulfill the request. This is the appropriate response when the
  IPP Printer does not recognize an operation and is not capable of
  supporting it for any object.

  4.4.3.5 204 Printer Error

  A printer error, such as a paper jam or a memory overflow (i.e.
  the document data exceeds the memory of the Printer) occurs while
  the IPP Printer processes a Print operation.  The response shall
  contain the Job Status with the specific error and should contain
  a Message describing the error.  An IPP application should check
  the Job Status in the response for the specific error.

  4.4.4 Communication Error 3xx

  Response status codes beginning with the digit "3" indicate cases
  in which there are errors from the underlying transport services
  used to communicate IPP requests and responses between IPP
  clients and IPP servers.  IPP applications should display any
  included Message to the end-user.  Unless otherwise noted, these
  status codes apply to all operations.

  There will be a set of error conditions that are specific to the
  transport service selected by an IPP implementor.  An IPP
  implementor may choose to map all such transport errors to status
  code "300" or define additional status codes for the "3xx" class.

  4.4.4.1 300 Communication Error

  The IPP client encountered an unexpected condition which
  prevented it from fulfilling the request.

---

From: Tom Hastings <[email-masked]>
Date: Wed, 23 Apr 1997 14:37:54 PDT

Keith,

Great stuff!

Thanks for doing it.

I have some minor comments and an issue or 2.

Tom

>            | "001"      ; OK Attribute Substitution/

(1) I suggest that this be two separate success codes, since the user 
has to do different things depending on which condition to figure out 
what went wrong. Also need to make the description optionally plural, 
since there could be one or more:

             | "001"      ; Unimplemented Attribute(s) Ignored
             | "002"      ; Unsupported Attribute Value(s) Substituted

>                           Attribute Value Not Supported

(2) I suggest that these be two separate codes.  How about:

             | "109"      ; Some Attribute(s) Unimplemented
             | "110"      ; Some Attribute Value(s) Unsupported

>            | "202"      ; IPP Version Not Supported

(3) I thought we had been counseled by Larry Masinter and the HTTP crowd to
design the protocol so that new versions were upwards compatible with
older versions.  Therefore, this error should not be an error.  The operation
not implemented might be the error if a newer client tries to work with
an older server.

Alternatively, we could include this error, but with the text that 
a conforming server shall NOT return it.  It is there just in case,
a future verson of the standard needs a conforming Printer to return it
to an older client.  At that time this sentence will be change to allow
a conforming Printer to return this error code.

>IPP status codes are extensible. IPP applications are not

(4) I think we need to make them type 2 keywords, correct?

(5) ISSUE: Do we also need a way to allow implementors to have private
error codes as well?

>and/or ignored at least one attribute that is not implemented.

(1') See above discussion on making this two separate warnings:

  001 Unimplemented Attribute(s) Ignored
  002 Unsuppored Attribute Value(s) Substituted

>and/or which attribute values are not supported by a Printer.

(7) This previous paragraph only applies to Gets, not Print operation.
Need to clarify.  The previous paragraph specifies the Print operation.

>are not supported by the Printer.

(2') See discusson above that suggests that we need two errors here:

  109 Some Attribute(s) Not Implemented
  110 Some Attribute Value(s) Not Supported

(6) Again, while this is good for the user, the group has agreed to require
the Printer to return the attributes in question in the response
to a Print operation.  But its easy for a query response.

(7) Here is a case where the description needs to be clarified for Print
vs Get-Attributes/Get-Jobs operations.

>operation, the Printer shall return this status.  

(8) ISSUE:
Since multiple documents isn't indicated by an attribute, but rather
by the content that is sent, we need a distinct error code:

  multiple-documents-not-supported

(if we allow a conforming Printer to reject a multiple document
job in a Print operation.)

>                                                   For another 

(9) The word "available" has not been defined and has caused a lot of
confusing in the past as to whether it means "supported" (which could
be ready or not ready) or "ready" (can be used without human intervention).

>versions are supported by that IPP Printer.

(3') See discussion above that we shouldn't have such an error, unless
we make an incompatible change between versions of the protocol.

---

From: [email-masked] (Robert Herriot)
Date: Wed, 23 Apr 1997 17:53:41 -0700

Thanks, Keith for doing all this work.  The functionality seems
to be mostly right, but I would expect that it would be better
to use the same Status codes as HTTP uses wherever there is overlap.
My table below shows that there is considerable overlap.

The following are the HTTP errors listed in RFC2068, plus the
functionality suggested by Keith.

I have put a mark in column 1 to denote:
   x should be in IPP Version 1.0
   f may be in a future version, so don't reuse error code
   i new concept for IPP not in HTTP (I started these error codes at x51)
 <blank> HTTP codes that IPP probably doesn't need, but I don't
     suggest reusing them.

I have put a k in column 2 if it was on Keith's list, and I have
put Keith's error number next to the k so you can see the similarities.

      Informational 1xx 
f     100 Continue 
f     101 Switching Protocols 
      Successful 2xx
xk000 200 OK 
x     201 Created  (for CreateJob instead of 200)
f     202 Accepted 
      203 Non-Authoritative Information 
x     204 No Content  (no entity body returned, e.g. with CancelJob)
      205 Reset Content 
      206 Partial Content 
ik001 251 OK Attribute Substitution/Attribute Ignored
          Tom suggested splitting these two. I disagree because both
          errors may occur in the same job. Details, if any, could
          be in the application/IPP entity body.
          We could also remove this error and put such information in
          the entity body and then use the 201 status code.
      Redirection 3xx 
      300 Multiple Choices 
f     301 Moved Permanently 
f     302 Moved Temporarily 
      303 See Other 
f     304 Not Modified 
      305 Use Proxy 
      Client Error 4xx 
xk100 400 Bad Request 
xk101 401 Unauthorized 
xk102 402 Payment Required 
xk103 403 Forbidden 
xk106 404 Not Found 
xk104 405 Method Not Allowed 
 k105   ? I don't think that a server should distiguish between "Forbidden"
             and "Operation Not Authorized". Generally security people
             don't like to be very specific about why a person was
             disallowed.
x     406 Not Acceptable 
      407 Proxy Authentication Required 
f     408 Request Timeout 
      409 Conflict 
xk107 410 Gone 
x     411 Length Required 
      412 Precondition Failed 
x     413 Request Entity Too Large 
x     414 Request-URI Too Long 
      415 Unsupported Media Type 
ik109 451 Attribute Not Implemented/Attribute Value Not Supported
          Tom suggested splitting these two. I disagree because both
          errors may occur in the same job. Details, if any, could
          be in the application/IPP entity body.
      Server Error 5xx 
xk200 500 Internal Server Error 
xk203 501 Not Implemented 
      502 Bad Gateway 
xk201 503 Service Unavailable 
      504 Gateway Timeout 
xk202 505 HTTP Version Not Supported 
 k204 551 Printer Error
 k300 I don't understand how the protocol generates what seems to
      be a client connection problem

---

From: [email-masked]
Date: Fri, 25 Apr 1997 12:17:47 -0500

Tom,

  Good feedback.  My answers to your questions and issues are inline as
  KC>>.

  Keith

  --- snip ---

  KC>> I combined these conditions into a single status code since both
  KC>> conditions can occur in the same request.
  KC>> For the message, how about: "OK Attribute(s) Substituted/
  KC>> Attribute(s) Ignored".

  --- snip ---

  KC>> I combined these conditions into a single status code since both
  KC>> conditions can occur in the same request.
  KC>> For the message, how about: "Attribute(s) Not Implemented/
  KC>> Attribute(s) Not Supported".

  --- snip ---

  KC>> The HTTP 1.1 RFC includes status "505 HTTP Version Not Supported".
  KC>> The description of this status references another section in the
  KC>> HTTP 1.1 RFC that explains how an HTTP version is defined and
  KC>> identified. This same section is in the HTTP 1.0 internet draft
  KC>> although the "505" status is not in the internet draft.  "505"
  KC>> is returned when the server does not support the <major> version
  KC>> of the protocol as indicated in the request. Here is an excerpt
  KC>> from the HTTP 1.1 RFC:
  KC>>
  KC>> "HTTP uses a <major>.<minor> numbering scheme to indicate
  KC>> versions of the protocol. ... The <minor> number is incremented
  KC>> when the changes made to the protocol add features which do not
  KC>> change the general message parsing algorithm... The <major> number
  KC>> is incremented when the format of a message within the protocol
  KC>> is changed."
  KC>>
  KC>> I think we need a similar section in the Model spec and that we
  KC>> should adopt the HTTP <major>.<minor> numbering scheme.  i.e.
  KC>> IPP 1.0 is designated as "IPP/1.0".  Do you and others agree?
  KC>> If so, I'll write the section.
  KC>>
  KC>> The Model spec can state the following for "505":
  KC>>
  KC>> "This status code is reserved for future use.  A conforming IPP
  KC>> client shall specify an IPP version of IPP/1.0 in each request.
  KC>> A conforming IPP server shall not return this status code to a
  KC>> conforming IPP client."
  KC>>
  KC>> This last sentence covers the case where a non-conforming IPP client
  KC>> sends the wrong <major> number to a conforming IPP server and
  KC>> hopefully influences IPP servers to handle this situation gracefully
  KC>> if future IPP clients support new <major> versions of IPP.
  KC>> Your thoughts?

  KC>> Yes, we need to make status codes type 2 keywords.  I'll change
  KC>> "extension-code = 3DIGIT" to "extension-code = type 2 keyword".

  KC>> Does this mean we need another status class for private error
  KC>> codes?  If so, IPP applications must be told to treat all such
  KC>> error codes as "errors".  Are these type 4 keywords?

  --- snip ---

  KC>> Please see my answer to (1).

  >and/or which attribute values are not supported by a Printer.

  (6a) This previous paragraph only applies to Gets, not Print operation.
  Need to clarify.  The previous paragraph specifies the Print operation.

  KC>> I agree.  Here is revised text:
  KC>>
  KC>> "An IPP application may issue a Get-Attributes operation and
  KC>> specify the job-template group in the request to a Printer and
  KC>> then examine the attributes and/or attribute values in the
  KC>> response to determine which attributes are not implemented and/or
  KC>> which attribute values are not supported by the Printer."

  --- snip ---

  >request correctly, the Printer shall return this status [ and
  >are not supported by the Printer].

  KC>> Please see my answer to (2).

  KC>> I believe the group has agreed NOT to require the Printer to
  KC>> return the attributes in question in the response to a Print
  KC>> operation.  Rather, an IPP application can issue the
  KC>> Get-Attributes operation on the Printer to get this information.
  KC>> I'll remove the phrase bounded by [] in the 1st paragraph of "109"

  KC>> Per the conformance section, I do not believe a conforming IPP
  KC>> server can return this status code on a Get-Attributes operation.
  KC>> A conforming IPP server can only return this status code on a
  KC>> Get-Jobs operation in the situation already documented in the
  KC>> paragraph that follows prefixed with "*".

  (8) ISSUE:

  KC>> The description of number-of-documents states the following:
  KC>> "The printer shall reject a job if the number of documents is
  KC>> not in the range of this attribute." So, currently we require a
  KC>> conforming Printer to reject a multiple document job in a Print
  KC>> operation.
  KC>>
  KC>> Based on the Model spec, I understand that a Printer must detect
  KC>> document boundaries in the Print request to set number-of-documents.
  KC>> It seems if a Printer detects a document boundary for the "n+1"
  KC>> document (where "n" is the maximum value of number-of-documents
  KC>> supported by the Printer), then the Printer shall delete any spool
  KC>> space (if the Printer has a spooler) and any job configuration
  KC>> information (e.g. job id) used so far for the Job and reject the
  KC>> Print request.
  KC>>
  KC>> Ideally, it would be better if the IPP client set number-of-documents
  KC>> on a Print request so the target Printer can reject the Print
  KC>> request BEFORE spooling part of the job and/or setting up other
  KC>> information about the job (such as a job id).  I expect a GUI or a
  KC>> command line (both IPP applications) will allow an end-user to
  KC>> select one or more documents and then submit the Print request so
  KC>> the IPP application could specify number-of-documents on the Print
  KC>> request (assuming the application didn't validate this value before
  KC>> submitting the request).  If we require the client to specify
  KC>> number-of-documents (i.e. we make this attribute MANDATORY), then
  KC>> number-of-documents becomes just another attribute specified by
  KC>> the IPP client and so this status code applies.  Your thoughts?

  >For another example, if the Print operation specifies do-not-substitute,

  KC>> I'll change the phrase "available on" to "supported by".

  *>For a Get-Jobs operation, if the IPP Printer does not support at
  *>least one attribute value for Job Owner and/or Job States in
  *>the request, the Printer shall return this status and indicate
  *>in the response which attributes and/or attribute values are not
  *>supported by the Printer.

  >and/or which attribute values are not supported by a Printer.

  KC>>  I'll reword the above paragraph to match the answer to 6a.

  --- snip ---

  KC>> Please see my answer to (3).

  --- snip ---
  end of note

---

From: [email-masked] (Robert Herriot)
Date: Fri, 25 Apr 1997 17:21:24 -0700

> From [email-masked] Fri Apr 25 10:53:38 1997
>   Tom, 

If we accept the value syntax in my protocol document, keywords must start with
an ALPHA so that they are distinguishable from integer. So the extension-code
should not be a type 2 keyword, though it may be a type 2 integer.

>     multiple-documents-not-supported

There is another way around this problem.  If we believe that jobs are
always encoded in MIME, then the attribute formats-supported contains
values, such as application/postscript and application/vnd.hp-PCL.  If
the formats-supported attribute also contains a value of
multipart/mixed, then the Printer accepts multiple documents.