API Common Exceptions and Tips for Handling

Transcription

1 API Common Exceptions and Tips for Handling FOR ADP AUTHORIZED USERS ONLY All Rights Reserved. These materials may not be reproduced in any format without the express written permission of ADP, LLC. ADP provides this publication as is without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. ADP is not responsible for any technical inaccuracies or typographical errors which may be contained in this publication. Changes are periodically made to the information herein, and such changes will be incorporated in new editions of this publication. ADP may make improvements and/or changes in the product and/or the programs described in this publication. CONTENTS Overview Exceptions Overview This document lists common Application Programming Interface (API) exception response codes and tips to handle each. ADP recommends developers review these exceptions when integrating with ADP APIs. NOTE: These common exceptions apply to all ADP APIs. Exception codes and errors specific to individual APIs are not covered in this document. Exceptions

2 Code Description Missing or duplicate parameters Exception Condition Response How to Handle Access Token call is made without grant_type para meter. "error_description": "Missing or duplicate parameters" Make sure the grant_type parameter is set in the Access Token call. Invalid grant_type Access Token call is made with invalid grant_type. "unsupported_grant_type", "error_description": "Invalid grant_type" Make sure the correct value is sent for the grant_type parameter. EXAMPLE: grant_type=client_cre dentials Validation error Token is missing in the request or invalid token is sent in the request. "error_description": "Validation error" Make sure the correct token is included in the request. Invalid / Missing Role code For the associated feature, Role Code is not found or enabled for the requestor. "codevalue": "error", "usermessage": "messagetxt": "Invalid / Missing In ADP product, assign the proper actor permission for the HTTP requestor.

3 Role code", For further help contact your ADP representative. 401 Unauthorized 401 Unauthorized The given client credentials were not valid proper client ssl certificate was not presented The Client ID or Client Secret entered is invalid for the Access Token call. Proper Secure Sockets Layer (SSL) certificates are not sent. "invalid_client", "error_description": "The given client credentials were not valid" "error_description": "proper client ssl certificate was not presented" Verify the correct Client ID and Client Secret are being passed. Make sure valid SSL certificates are sent in the request. Subscription status is suspended The client suspended a subscription to the data connector application. "access_denied", "error_description": "Subscription status is suspended" Verify your client's subscription status. Then, contact your client to activate the subscription. Consent not provided The client has not provided consent or suspended consent to the data connector application. "access_denied", Ask the client to provide consent to your data connector application. For more information, you can refer them to Using

4 invalid_scope The API request is not authorized Operation Not Permitted 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. The calling HTTP request does not have the right authorization for the underlying ADP application feature. "error_description": "Consent not provided " 'error_code': 'invalid_scope', 'error_description': 'The requested scope is not allowed' ["messagetypecode":"codevalue":" error","usermessage":"messagetxt":" Operation Not Permitted","developerMessage":"cod evalue":"c820b424-1f4f a3fc1417b8"] Consent Manager to Control Access to Your Data. To add the API to your application scope, contact your ADP representative. Make sure you provide the following: Your organization name Application name List of the APIs to be added 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 scope for this service is An Invalid URI is being used in the request Make sure the correct URI is included in the request.

5 invalid or undefined 'error': 'invalid_scope', 'error_description': 'scope for this service is invalid or undefined' 503 Service Unavailable Failed to retrieve consent status The client consent record is not available. "temporarily_unavailable", Contact your ADP representative. "error_description": "Failed to retrieve consent status" 503 Service Unavailable infrastructure is temporarily unavailable ADP service is not available "temporarily_unavailable", Try again. If the errors occurs again, contact your ADP representative. "error_description": "infrastructure is temporarily unavailable"