Clarify error responses and allow nonHTTP error codes General Recommendations for REST Include the HTTP status code for clients that cant read this from the response Include a provider specific error code for more granular error information ID: 589478
Download Presentation The PPT/PDF document "Ticket #46" is the property of its rightful owner. Permission is granted to download and print the materials on this web site for personal, non-commercial use only, and to display it on your personal computer provided you do not modify the materials and that you retain all copyright notices contained in the materials. By downloading content from our website, you accept the terms of this agreement.
Slide1
Ticket #46Clarify error responses and allow non-HTTP error codesSlide2
General Recommendations for RESTInclude the HTTP status code for clients that can't read this from the response.
Include a provider specific error code for more granular error information.
Include a human-readable error that can be presented to an end user.
Include a detailed error that can be used by a developer to diagnose the problem.Include links to online resources with more information about the error.
http://
soabits.blogspot.com/2013/05/error-handling-considerations-and-best.html
https://tools.ietf.org/html/draft-nottingham-http-problem-04Slide3
Recommendation: Use Problem DetailsPros
Includes user and
and
developer information in title (required) and detail (optional) fields.Includes HTTP status code (optional) in httpStatus field.Includes provider-specific status code (required) in
problemType
field.Slide4
Recommendation: Use Problem DetailsCons
SCIM requires HTTP status code, but this is optional in Problem Details.
SCIM may wish to dictate that this is required.
The problemType field is required and is defined as:"An absolute URI [RFC3986] that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML).“
It is a nice feature to make this
dereferenceable
, but could be seen as an imposition on some service providers.Slide5
Example
HTTP/1.1 401 Unauthorized
Content-Type: application/
api-problem+json
Content-Language: en
{
"
problemType
": "
http://example.com/errors/insufficient-access", "title": "You do not have the required permissions to create a new user.", "detail": "Creating a user requires RIGHT_CREATE_USER."}
Note: This is now single-valued instead of multi-valued. Multi-valued errors are typicallyused to communicate errors per field in a request.
Provider-specific code
User-friendly message
Developer-friendly message