Error Handling

LinkedIn encourages developers to handle errors in a good manner. Therefore we provided concise error codes and messages to allow for easy error handling.

In this page, we will show error codes and their corresponding messages on API calls and OAuth 2.0 flow. More importantly, this will provide a better understanding and how to effectively handle them in your application.

Error Response Format Sample

With LinkedIn, you have to make an authorized API call along with a valid access token on the behalf of a LinkedIn member. A 401 unauthorized error will return if failed to do so as the following example shows.

GET
https://api.linkedin.com/v2/me
Sample error API response
{
  "status": 401,
  "serviceErrorCode": 401,
  "message": "Empty oauth2_access_token"
}

The error response shows you the following fields:

  • status - Indicates the type of an error.
  • message - Textual detailed description of the error.
  • serviceErrorCode - A subcode indicates further classification of the error.

Please check next section HTTP Status Codes and Error Types about more details of status and serviceErrorCode

HTTP Status Codes and Error Types

LinkedIn uses standard HTTP status codes for each API’s response (https://tools.ietf.org/html/rfc2616#section-10). Successful requests return HTTP status codes in 2xx. Failed requests due to client errors return HTTP status codes in 4xx, and server errors in 5xx relatively. And this section only provides a list of details for 4xx and 5xx, since these are what you application would need to handle in most cases.

400 Bad Request

Generally, this type of errors dues to an apparent client mistakes preventing the server to proceed the request. The most common case is malformed syntax in the request URL or body. This issue usually is caused by mis-typing on the application side (e.g GET /v2/m%e). Some useful ways help to fix an issue like this are:

  • Check if any invalid character is included for the URL
  • Check our API samples
  • Ask your colleague for help
  • Talk to the rubber duck

401 Unauthorized

This kind of errors is normally caused by a problem of the request header along with your API call.  Some common cases are:

Error Type Suggestion
Unknown authentication schema

It indicates unrecognized schema of the authentication header while making the API request. Please check if the authentication header is in the same format as

 

    Authorization: Bearer [your access token]

 

Empty OAuth2 access token It indicates that authentication header is missing or empty. Please check if the authentication header is in the same format as the sample shows above.
Invalid access token It indicates incorrect access token, please make sure you have followed our procedures from authenticating with OAuth 2.0 to get a correct access token.
Expired access token It indicates that the access token has expired, please see how to refresh the access token correctly.
The token has been revoked It indicates that the access token has been revoked by the user from their privacy settings on LinkedIn’s website. If she would like to continue using your application, she would need to authenticate with OAuth 2.0 to grant a correct access token for your application again.

Note: In case of downstream failures in verification of the access token, you will receive a 500 error response back.

403 Access Denied

With LinkedIn platform, each REST API requires a correct application permission. When your application makes a API call with the user’s access token, LinkedIn checks if the access token has been granted proper permission to access this API, unless a 403 will be returned. When the issue happens, mostly it can be fixed by asking the following questions:

  • Does my application have permissions to make such a API call?
  • Does my application enable these permissions to ask the user to grant them to my application?
  • Application Permissions

If you would not be able to answer any above question (e.g your application doesn’t have the relative permission), or still can not fix the issue even that all questions above have been fixed, please reach out to your partner technical support channel or https://developer.linkedin.com/support.

404 Resource Not Found

Most of time, this indicates the API that your application requests doesn’t exist. For instance, the API to get a friend’s profile is /v2/people/id={personId}, rather than /v2/person/id={personId}. In addition, you need be aware that, in some case (e.g Ads), your application would get a 404 for restricted API access. If this is the issue you are experiencing at the moment, please check 403 Access Denied first, and then ask your partner technical support channel if the issue remains.

405 Method Not Allowed

It indicates the HTTP protocol methods your request was making is not supported. Please check our relevant docs of the API your application was calling, and all supported methods would be addressed there.

429 Rate Limit

With LinkedIn platform, all API requests are rate limited to prevent abuse and ensure service stability. When this error happens, it’s always good to check if too many redundant calls are being made along with your application’s settings. And if you have confirmed that rate limits could not meet your application’s need, please contact us if you are our partner now, or join our partner program through https://developer.linkedin.com/partner-programs. We’d love to hear the story from your side, and help to make it happen.

500 Internal Server Error

It indicates an internal server error on LinkedIn side. If this issue continuously happens, please report to your partner technical support channel or https://developer.linkedin.com/support, and we will have it to be fixed as soon as possible.

504 Gateway Timeout

It indicates that it takes too long to proceed the API call on LinkedIn side. Due to the nature of cloud APIs, services can be temporarily unavailable due to reasons outside of your or LinkedIn's control. It’s wise to have proper error handling logic to cover issues like this (e.g. caching and retry patterns). If your application is continuously experiencing this issue, please report to us and we will investigate what’s happening internally.