Developer Blog Series: How To Handle Common SKY API Errors
Published
It would be wonderful if every call to a SKY API had valid data, proper formatting, and an environment that was never in a bad state. Unfortunately, things don’t always work that way. Many problems can occur during an API request, ranging from bad requests to insufficient permissions to issues with SKY API itself. This blog post describes some errors that you may encounter with SKY API and how to resolve them or avoid them altogether.
Bad Requests
One of the most common SKY API errors is the 400 status code that indicates a bad request. This status code usually means that data in the initial request is invalid or improperly formatted. For example, if you pass in the string “panda” for the
birthdate property on a constituent, the response returns a 400 status code because the property’s type is fuzzy date and “panda” is not a valid fuzzy date. The cause of the bad request is described in the error message on the response:
SKY API also returns the 400 status code if a request is missing data for a required field or if it does not conform to special cases that we call out in the endpoint documentation. For example, you cannot pass both the sort and sort_token parameters in a request to the Constituent list endpoint because both parameters sort the resulting list. If you pass in both parameters, the sorting method cannot be discerned, and the API returns the 400 status code.
When you receive a 400 response, the best way to handle the error is to determine the cause and alter the request to make it valid. We also recommend that you validate the data in your requests before you submit them to ensure that the requests will succeed.
Unauthorized Requests
Another common SKY API error is the 401 status code that indicates the caller of the request does not have sufficient privileges to perform the requested action. The 401 status code could mean that the authenticated user does not have rights to access the requested data, or it could mean the user does not have permission to edit a given record or record type. To handle 401 responses, let users know that they do not have the required permissions so that they can consult with a manager or administrator.
An unauthorized request also occurs if the authorization token expires or if you do not supply the authorization header. Your application should manage the authorization token to ensure that it is supplied on each request and that it is replaced when it expires. Our authorization documentation describes the issues that can occur in the authorization code flow, and the authorization code flow code samples provide basic examples of how to interact with the authorization service.
Rate Limits and Quotas
Another issue that can occur during SKY API requests is exceeding the rate limit or quota. The rate limit prevents too many requests during short periods of time. If you reach this limit, requests return the 429 response with
retry-after headers that indicate how long to wait before you retry the requests. For more information about rate limits and how to handle 429 responses, see the request throttling blog post.SKY API also employs a quota limit to manage API traffic over a broader period of time. If you reach this limit, requests return the 403 (Forbidden) status code with
retry-after headers that indicate how long to wait before you call the API again. As with the 429 responses, we recommend that you wait and retry after the time period in the retry-after header.
Internal Server Errors
Another common SKY API error is the 500 status code that indicates something went wrong on Blackbaud’s end. We strive to avoid this, so 500 errors should be rare. However, you will likely encounter an internal service error at some point. If this happens, please post about it in the Community so that we can log the issue and prevent it in the future. Any information that you can provide is helpful, including steps to reproduce the issue, data associated with the request, and when the request occurred. We are grateful for the wonderful help we receive from the Community to identify and resolve issues.
To handle a response with the 500 status code, we recommend that you wait for a short time and then attempt the request again. For example, we implemented a wait and retry for 500s as part of our Barkbaud sample application. Here is the code that handles 429 and 500 status codes:
Issues with Data Synchronization
If you synchronize data with SKY API using the
sort_token method that we recommend in the synchronization blog post, be sure to handle any 429 or 500 status codes. If you do not handle bad responses, data likely will not synchronize completely, and it will be difficult to determine what data was skipped. When you encounter a bad response, we recommend that you wait for a short time and then attempt the request again. If the subsequent request fails or if a 429 status code indicates that you reached the rate limit, we recommend that you cache the next_link/sort_token until you can make a clean, successful call to continue the data sync. With the next_link/sort_token cached, the data sync can resume without losing its position.For more information about status codes, rate limits, and quotas, we recommend that you review the SKY API website:
Thank you! :D
News
SKY Developer Announcements
02/07/2019 3:56pm EST
Leave a Comment
We are getting “Authorization has been denied for this request.” for SKYAPI(FENXT), any idea why?