API Common Exceptions and Tips for Handling

400 Bad Request

Indicates missing or duplicate parameters.

An Access Token call is made without a grant_type parameter.

{
"error": "invalid_request",
"error_description": "Missing or duplicate parameters"
}

Make sure the grant_type parameter is set in the Access Token call.

400 Bad Request

Indicates an invalid grant_type.

An Access Token call is made with an invalid grant_type.

{
    "error": "unsupported_grant_type",
    "error_description": "Invalid grant_type"
}

Make sure the correct value is sent for the grant_type parameter.
For example:
grant_type=client_credentials

400 Bad Request

Indicates a Validationerror.

The token is missing in the request or an invalid token is sent in the request.

{
    "error": "invalid_request",
    "error_description": "Validation error"
}

Make sure the correct token is included in the request.

400 Bad Request 

Indicates an Invalid/Missing Role code.

For the associated feature, Role Code is not found or enabled for the requestor.

processMessages": [{"userMessage": {"messageTxt": "Invalid / Missing Role code"

In an ADP product, assign the proper actor permission for the HTTP requestor.

For further help contact your ADP representative.

401 Unauthorized Error

Indicates that the given client credentials were not valid.

The Client ID or Client Secret entered is invalid for the Access Token call.

{
"error": "invalid_client",
"error_description": "The given client credentials were not valid"
}

Verify the correct Client ID and Client Secret are being passed.

401 Unauthorized Error

Specifies the proper client secure sockets layer (SSL) certificate was not presented.

Proper Secure SSL certificates are not sent.

{
"error": "invalid_request",
"error_description": "proper client ssl certificate was not presented"
}

Make sure valid SSL certificates are sent in the request.

403 Forbidden Error

Indicates the subscription status is suspended.

The client suspended a subscription to the data connector application.

{
"error": "access_denied",
"error_description": "Subscription status is suspended"
}

Verify your client's subscription status. Then, contact your client to activate the subscription.

403 Forbidden Error

Indicates consent has not been provided.

The client has not provided consent or has suspended consent to the data connector application.

{
    "error": "access_denied",
    "error_description": "Consent not provided "}

Ask the client to provide consent to your data connector application.
For more information, refer your client to Using Consent Manager to Control Access to Your Data.

403 Forbidden Error

Indicates an invalid_scope.

The API request is not authorized in your application scope. When your consumer application needs to use extra APIs, contact your ADP representative to add each API to your application scope.

{
'error_code': 'invalid_scope',
'error_description': 'The requested scope is not allowed'
}

To add the API to your application scope, contact your ADP representative. Make sure you provide the following:

• Organization name
• Application name
• List of APIs to be added

403 Forbidden Error

The calling HTTP request does not have the right authorization for the underlying ADP application feature.

{"messageTxt":"Operation Not Permitted"},

Do the following:

1. Verify the client has the feature turned on within the application from which the API is trying to access data. 
2. Verify the calling HTTP request/user has data access. For example, ADP Workforce Now uses profiles to manage data access for a group of people. The API requestor needs to be configured under the right profile, which needs to have access to the data being requested by the API.

404 Not Found

Indicates the scope for this service is invalid or undefined.

An Invalid URI is being used in the request.

{
  'error': 'invalid_scope',
  'error_description': 'scope for this service is invalid or undefined'
  }

Make sure the correct URI is included in the request.

503 Service Unavailable

Failed to retrieve consent status.

The client consent record is not available.

{
"error": "temporarily_unavailable",
"error_description": "Failed to retrieve consent status"
}

Contact your ADP representative.

503 Service Unavailable

Specifies that infrastructure is temporarily unavailable.

ADP service is not available.

{ 
"error": "temporarily_unavailable",
"error_description": "infrastructure is temporarily unavailable"
}

Try again.
If the errors occurs again, contact your ADP representative.