OpenSSO / OpenAM REST Status Codes

OpenAM REST APIs respond to successful requests with HTTP status codes in the 2xx range. OpenAM REST APIs respond to error conditions with HTTP status codes in the 4xx and 5xx range. Status codes used are described in the following list.

200 OK
The request was successful and a resource returned, depending on the request. For example, a successful HTTP GET on /users/myUser returns a user profile and status code 200, whereas a successful HTTP DELETE returns {"success","true"} and status code 200.

201 Created
The request succeeded and the resource was created.

400 Bad Request
The request was malformed. Either parameters required by the action were missing, or as in the following example incorrect data was sent in the payload for the action.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"bad":"data"}' \
https://openam.example.com:8443/openam/json/users?_action=forgotPassword

{
"code":400,
"reason":"Bad Request",
"message":"Username or email not provided in request"
}
401 Unauthorized
The request requires user authentication as in the following example, which is missing an SSO Token value.

$ curl \
--request POST \
https://openam.example.com:8443/openam/json/sessions?_action=logout

{
"code": 401,
"reason": "Unauthorized",
"message": "Access denied"
}
403 Forbidden
Access was forbidden during an operation on a resource as in the following example, which has a regular user trying to read the OpenAM administrator profile.

$ curl \
--request POST \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: changeit" \
https://openam.example.com:8443/openam/json/authenticate

{ "tokenId": "AQIC5w...YyMA..*" }
$ curl \
--header "iplanetDirectoryPro: AQIC5w...YyMA..*" \
https://openam.example.com:8443/openam/json/users/amadmin

{
"code": 403,
"reason": "Forbidden",
"message": "Permission to perform the read operation denied to
id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
}
404 Not Found
The specified resource could not be found as in the following example, which is attempting to read a nonexistent user’s profile.

$ curl \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
https://openam.example.com:8443/openam/json/users/missing

{
"code":404,
"reason":"Not Found",
"message":"Resource cannot be found."
}
405 Method Not Allowed
The HTTP method is not allowed for the requested resource.

406 Not Acceptable
The request contains parameters that are not acceptable as in the following example, which specifies an API version parameter that is not supported by OpenAM.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: changeit" \
--header "Accept-API-Version: protocol=1.0, resource=999.0" \
https://openam.example.com:8443/openam/json/authenticate
{
"code":406,
"reason":"Not Acceptable",
"message":"Accept-API-Version: Requested version \"999.0\" does not match any routes."
}
409 Conflict
The request would have resulted in a conflict with the current state of the resource. For example using the Forgot Password feature and specifying the user’s email address as in the following example, where multiple users have the same email address.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"email":"demo@example.com"}' \
https://openam.example.com:8443/openam/json/users?_action=forgotPassword

{
"code":409,
"reason":"Conflict",
"message":"Multiple users found"
}
410 Gone
The requested resource is no longer available, and will not become available again. The URI returned for resetting a password may have expired as in the following example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"username": "demo"}' \
https://openam.example.com:8443/openam/json/users/?_action=forgotPassword

{
"code":410,
"reason":"Gone",
"message":"Token not found"
}
415 Unsupported Media Type
The request is in a format not supported by the requested resource for the requested method as in the following example, which is attempting to pass basic authentication credentials as form-encoded data rather than query string parameters.

$ curl \
--request POST \
--data "username=demo&password=changeit" \
https://openam.example.com:8443/openam/json/authenticate

...
HTTP Status 415
...
The server refused this request because the request entity is in a
format not supported by the requested resource for the requested method
...
500 Internal Server Error
The server encountered an unexpected condition which prevented it from fulfilling the request. This could be caused by an invalid configuration in the Email Service, or as in the following example the specified user account not having an associated email address to send the Forgot Password URI to.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"username": "demo"}' \
https://openam.example.com:8443/openam/json/users/?_action=forgotPassword

{
"code":500,
"reason":"Internal Server Error",
"message":"No email provided in profile."
}
501 Not Implemented
The resource does not support the functionality required to fulfill the request as in the following example, which is attempting to delete an entry as a delete action instead of using an HTTP DELETE request.

$ curl \
--request POST \
--header "iplanetDirectoryPro: AQIC5w...NTcy*" \
https://openam.example.com:8443/openam/json/users/demo?_action=delete

{
"code": 501,
"reason": "Not Implemented",
"message": "Actions are not supported for resource instances"
}
503 Service Unavailable
The requested resource was temporarily unavailable. The service may have been disabled, as in the following example, where the Forgot Password functionality has been disabled.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"username": "demo"}' \
https://openam.example.com:8443/openam/json/users/?_action=forgotPassword

{
"code":503,
"reason":"Service Unavailable",
"message":"Forgot password is not accessible."
}

Leave a Reply

Your email address will not be published. Required fields are marked *