OWS Common 1.1 Change Request - Use HTTP status codes for OGC Exceptions
OGC Doc 08-143r1
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
OWS 1.1 CR ?
rev
1.1
Current version:
1.1
For HELP on using this form, see bottom of this page or look at the pop-up text over the symbols.
Proposed change affects:
AS
Imp Spec X
Best Practices Paper
Other
Title:
OWS Common 1.1 Change Request – Use HTTP status codes for OGC exceptions
Source:
Steven Keens, PCI Geomatics
Work item code:
Category:
Date: September 2, 2008
C
Use one of the following categories:
F (Critical correction)
A (corresponds to a correction in an earlier
release)
B (Addition of feature),
C (Functional modification of feature)
D (Editorial modification)
Detailed explanations of the above categories can
be found in the TC Policies and Procedures.
Reason for change:
Currently most, if not all, OGC services always return HTTP status code 200 (OK)
for all requests, even when the request results in an exception. It is better to
return a more appropriate HTTP status code (such as 400, 500, etc).
Note that, Annex A – Abstract Test Suite, which is normative, contains a clause
“A.4.1.5 HTTP response status code” that already tests for this condition. Thus
the requirement already exists, it’s just that the standard never documented the
status codes to use.
Summary of change: Added section that maps OGC Exception codes to standard HTTP status codes.
Consequences if
not approved:
Client implementers have to do a deep analysis of the contents to determine if an
exception was received or not. Implementations will be simpler if this is adopted.
HTTP response messages with status codes indicating an error may not be
cached anywhere between and including the client and server thus saving
resources for correct responses.
Clauses affected:
Add clause 8.6
Other specs
Affected:
Supporting Doc.
X Other core specifications
Abstract specifications
Best Practices Document
Other comments:
Status
Disposition
All standards dependant on OWS Common
The OGC Technical Committee Policies & Procedures 05-020r3
1.1
HTTP STATUS codes for OGC Exceptions
When an OWS instance would respond with an ExceptionReport and when the report is
transmitted via HTTP the OWS instance shall set the HTTP response’s status code to the
corresponding value for the given exceptionCode values, as shown in Table 26. When the
ExceptionReport contains more than one Exception then the HTTP status code value shall
be based upon the exceptionCode of the first Exception in the ExceptionReport.
OWS specifications specifying additional exceptionCode values shall provide a
corresponding HTTP status code value for every new exceptionCode. A comprehensive
list of HTTP status codes is available in clause 10, Status Code Definitions, of [IETF
RFC 2616]. A more accessible list is available at
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
Table 26 — Standard exception codes and meanings
exceptionCode value
OperationNotSupported
MissingParameterValue
InvalidParameterValue
VersionNegotiationFailed
InvalidUpdateSequence
OptionNotSupported
NoApplicableCode
HTTP Status Code
Code
Message
501
400
400
400
400
501
500
Not Implemented
Bad request
Bad request
Bad request
Bad request
Not Implemented
Internal Server Error
An example showing an HTTP response with the status code 400 and the body containing
an ExceptionReport is:
HTTP/1.1 400 Bad Request
Date: Thu, 4 Sep 2008 06:20:15 GMT
Content-Type: application/xml
Content-Language: en
Content-Length: 493
Last Revision Date: 2 December 2017
Page 2
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
OWS 1.1 CR ?
rev
1.1
Current version:
1.1
For HELP on using this form, see bottom of this page or look at the pop-up text over the symbols.
Proposed change affects:
AS
Imp Spec X
Best Practices Paper
Other
Title:
OWS Common 1.1 Change Request – Use HTTP status codes for OGC exceptions
Source:
Steven Keens, PCI Geomatics
Work item code:
Category:
Date: September 2, 2008
C
Use one of the following categories:
F (Critical correction)
A (corresponds to a correction in an earlier
release)
B (Addition of feature),
C (Functional modification of feature)
D (Editorial modification)
Detailed explanations of the above categories can
be found in the TC Policies and Procedures.
Reason for change:
Currently most, if not all, OGC services always return HTTP status code 200 (OK)
for all requests, even when the request results in an exception. It is better to
return a more appropriate HTTP status code (such as 400, 500, etc).
Note that, Annex A – Abstract Test Suite, which is normative, contains a clause
“A.4.1.5 HTTP response status code” that already tests for this condition. Thus
the requirement already exists, it’s just that the standard never documented the
status codes to use.
Summary of change: Added section that maps OGC Exception codes to standard HTTP status codes.
Consequences if
not approved:
Client implementers have to do a deep analysis of the contents to determine if an
exception was received or not. Implementations will be simpler if this is adopted.
HTTP response messages with status codes indicating an error may not be
cached anywhere between and including the client and server thus saving
resources for correct responses.
Clauses affected:
Add clause 8.6
Other specs
Affected:
Supporting Doc.
X Other core specifications
Abstract specifications
Best Practices Document
Other comments:
Status
Disposition
All standards dependant on OWS Common
The OGC Technical Committee Policies & Procedures 05-020r3
1.1
HTTP STATUS codes for OGC Exceptions
When an OWS instance would respond with an ExceptionReport and when the report is
transmitted via HTTP the OWS instance shall set the HTTP response’s status code to the
corresponding value for the given exceptionCode values, as shown in Table 26. When the
ExceptionReport contains more than one Exception then the HTTP status code value shall
be based upon the exceptionCode of the first Exception in the ExceptionReport.
OWS specifications specifying additional exceptionCode values shall provide a
corresponding HTTP status code value for every new exceptionCode. A comprehensive
list of HTTP status codes is available in clause 10, Status Code Definitions, of [IETF
RFC 2616]. A more accessible list is available at
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
Table 26 — Standard exception codes and meanings
exceptionCode value
OperationNotSupported
MissingParameterValue
InvalidParameterValue
VersionNegotiationFailed
InvalidUpdateSequence
OptionNotSupported
NoApplicableCode
HTTP Status Code
Code
Message
501
400
400
400
400
501
500
Not Implemented
Bad request
Bad request
Bad request
Bad request
Not Implemented
Internal Server Error
An example showing an HTTP response with the status code 400 and the body containing
an ExceptionReport is:
HTTP/1.1 400 Bad Request
Date: Thu, 4 Sep 2008 06:20:15 GMT
Content-Type: application/xml
Content-Language: en
Content-Length: 493
Last Revision Date: 2 December 2017
Page 2