Enhanced Error Codes
- Topics:
- Authentication
Enhanced Error Codes represent an Adobe Pass Authentication feature that provides additional error information to client applications integrated with:
-
Adobe Pass Authentication REST APIs:
-
Adobe Pass Authentication SDKs Preauthorize API:
- (Legacy) JavaScript SDK (Preauthorize API)
- (Legacy) iOS/tvOS SDK (Preauthorize API)
- (Legacy) Android SDK (Preauthorize API)
(*) Preauthorize API is the only Adobe Pass Authentication SDK API that provides support for Enhanced Error Codes.
Representation
Enhanced Error Codes can be represented in JSON
or XML
format depending on the integrated Adobe Pass Authentication API and the used “Accept” header value (i.e., application/json
or application/xml
):
- Top-level error information: In this case, the “error” object is located at the top level, therefore the response body can contain only the “error” object.
- Item-level error information: In this case, the “error” object is located at the item level, therefore the response body can contain an “error” object for all items that experienced an error while being serviced.
REST API v2
Refer to the following HTTP responses containing Enhanced Error Codes examples represented as JSON
applicable for REST API v2.
HTTP/1.1 200 OK
Content-Type: application/json
{
"decisions": [
{
"resource": "REF30",
"serviceProvider": "REF30",
"mvpd": "Cablevision",
"source": "mvpd",
"authorized": true,
"token": {
"issuedAt": 1697094207324,
"notBefore": 1697094207324,
"notAfter": 1697094802367,
"serializedToken": "PHNpZ25hdHVyZUluZm8..."
}
},
{
"resource": "REF40",
"serviceProvider": "REF40",
"mvpd": "Cablevision",
"source": "mvpd",
"authorized": false,
"error" : {
"action": "none",
"status": 403,
"code": "authorization_denied_by_mvpd",
"message": "The MVPD has returned a \"Deny\" decision when requesting authorization for the specified resource",
"details": "Your subscription package does not include the \"Live\" channel",
"helpUrl": "https://experienceleague.adobe.com/docs/pass/authentication/auth-features/error-reportn/enhanced-error-codes.html",
"trace": "12f6fef9-d2e0-422b-a9d7-60d799abe353"
}
}
]
}
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"action": "none",
"status": 400,
"code": "invalid_parameter_service_provider",
"message": "The service provider parameter value is missing or invalid.",
"helpUrl": "https://experienceleague.adobe.com/docs/pass/authentication/auth-features/error-reportn/enhanced-error-codes.html",
"trace": "12f6fef9-d2e0-422b-a9d7-60d799abe353"
}
REST API v1
Refer to the following HTTP responses containing Enhanced Error Codes examples represented as JSON
or XML
applicable for REST API v1.
HTTP/1.1 200 OK
Content-Type: application/json
{
"resources": [
{
"id": "TestStream1",
"authorized": true
},
{
"id": "TestStream2",
"authorized": false,
"error": {
"action": "none",
"status": 403,
"code": "authorization_denied_by_mvpd",
"message": "The MVPD has returned a \"Deny\" decision when requesting authorization for the specified resource",
"details": "Your subscription package does not include the \"Live\" channel",
"helpUrl": "https://experienceleague.adobe.com/docs/pass/authentication/auth-features/error-reportn/enhanced-error-codes.html",
"trace": "12f6fef9-d2e0-422b-a9d7-60d799abe353"
}
}
]
}
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"action": "none",
"status": 400,
"code": "invalid_requestor",
"message": "The requestor parameter is missing or invalid.",
"helpUrl": "https://experienceleague.adobe.com/docs/pass/authentication/auth-features/error-reportn/enhanced-error-codes.html",
"trace": "8bcb17f9-b172-47d2-86d9-3eb146eba85e"
}
HTTP/1.1 400 Bad Request
Content-Type: application/xml
<error>
<action>none</action>
<status>400</status>
<code>invalid_requestor</code>
<message>The requestor parameter is missing or invalid.</message>
<helpUrl>https://experienceleague.adobe.com/docs/pass/authentication/auth-features/error-reportn/enhanced-error-codes.html</helpUrl>
<trace>8bcb17f9-b172-47d2-86d9-3eb146eba85e</trace>
</error>
Structure
Enhanced Error Codes include the following JSON
fields or XML
attributes with examples:
For more details, refer to the Action section.
For more details, refer to the Code section.
For more details, refer to the Response Handling section.
This field might not be present in case the services partner does not provide any custom message.
This field holds an absolute URL and should not be inferred from error code, depending on the error context a different URL can be provided.
Action
Enhanced Error Codes include an “action” field that provides a recommended action that might remediate the situation.
The possible values for the “action” field include:
(*) For some errors, multiple actions could be possible solutions, but the “action” field indicates the one with the highest probability of fixing the error.
Status
Enhanced Error Codes include a “status” field that indicates the HTTP status code associated with the error.
The possible values for the “status” field include:
Enhanced Error Codes with a 4xx “status” usually appear when the error is generated by the client and most of the time it implies that the client requires additional work to fix it.
Enhanced Error Codes with a 5xx “status” usually appear when the error is generated by the server and most of the time it implies that the server requires additional work to fix it.
Code
Enhanced Error Codes include a “code” field that provides an Adobe Pass Authentication unique identifier associated with the error.
The possible values for the “code” field are aggregated below in two lists based on the integrated Adobe Pass Authentication API.
Lists
REST API v2
The table below lists possible Enhanced Error Codes a client application might encounter when integrated with Adobe Pass Authentication REST API v2.
REST API v1
The table below lists possible Enhanced Error Codes a client application might encounter when integrated with Adobe Pass Authentication REST API v1.
SDKs Preauthorize API
Refer to the previous section for possible Enhanced Error Codes a client application might encounter when integrated with Adobe Pass Authentication SDKs Preauthorize API.
Response Handling
In summary, when handling responses containing Enhanced Error Codes, you should consider the following:
-
Check both status values: Always check both the HTTP response status code and the Enhanced Error Code “status” field. They might differ, and both provide valuable information.
-
Agnostic to top-level versus item-level error information: Handle top-level and item-level error information agnostic to the way it is communicated, ensure you can handle both forms of transmitting Enhanced Error Codes.
-
Retry logic: For errors that require a retry, ensure that retries are done with exponential backoff to avoid overwhelming the server. Also, in case of Adobe Pass Authentication APIs that handle multiple items at once (e.g., Preauthorize API), you should include in the repeated request only those items marked with “retry” and not the entire list.
-
Configuration changes: For errors that require configuration changes, ensure that the necessary changes are made before launching the new application or new feature.
-
Authentication and authorization: For errors related to authentication and authorization, you must prompt the user to re-authenticate or obtain new authorization as needed.
-
User feedback: Optional, use the human-readable “message” and (potential) “details” fields to inform the user about the issue. The “details” text message might get passed from the MVPD preauthorization or authorization endpoints or from the Programmer when applying degradation rules.