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.