ShareFile API
  • Not Currently Logged In |
    Log In
  • ||
    Logout
  • arrow Getting Started
    • Quick Start Guide
    • OData Implementation
    • FAQ
    • Authentication
    • Postman
    • Storage Zones
  • Get an API Key
  • arrow API Entities
    • AccessControls
    • Accounts
    • Apps
    • AsyncOperations
    • Capabilities
    • ConnectorGroups
    • Devices
    • EncryptedEmails
    • FavoriteFolders
    • Favorites
    • FolderTemplates
    • Groups
    • Items
    • Metadata
    • Policies
    • Reports
    • Sessions
    • Shares
    • StorageCenters
    • Users
    • WebhookClients
    • WebhookSubscriptions
    • Workflows
    • Zones
  • arrowWebhooks
    • Overview
    • Events
    • Payloads
    • Signature Keys
  • arrowHow-To Guides
    • Common Use Cases
    • Troubleshooting
  • arrowCode Samples
    • C#(.NET)
    • Command Line / CURL
    • PHP
    • Python
    • Ruby
    • VB(.NET)
  • arrowSDKs
    • PowerShell
    • .NET
    • JavaScript

Troubleshooting API Issues

ShareFile API requests can fail for a variety of reasons, and this guide is intended to help you identify and address API errors.

An unsuccessful ShareFile request will always return the following information in the response body:

  • Code: the standard http response code, e.g, Forbidden, Not Found, etc.
  • Message:
    • Lang: the language culture name of this message
    • Value: an error message explaining why the request failed

Here is a sample ShareFile API error response:

In modern programming languages like C# or PHP, failed HTTP requests will often throw an exception and show an error message similar to this one:

Error: The remote server returned an error: (500) Internal Server Error

This message is not very helpful in telling you what went wrong, which is why the ShareFile API will always return a JSON error response with a more detailed explanation of the failure. Therefore, make sure to always add exception handling to your code calling the ShareFile API! Your programming language will have a way to read the response content of a failed HTTP request so that you can read or log the error message, which will save you a lot debugging time.

If the error message is not clear enough or seems completely unrelated to the issue you are experienced, please contact us and we can help you figure out what’s wrong, as well as correct the vague message.

ShareFile API HTTP Response Codes

  • 200 OK This response indicates that your request was successfully executed, and the response content should contain the object you wanted to retrieve, create, or modify. If the response is successful, but the content is not what you expected, please contact us.
  • 204 No Content This response is commonly used for DELETE operations, and it indicates that the resource was deleted successfully.
  • 400 Bad Request This response indicates that there was a problem with the way the request was constructed. The error message property is particularly helpful in this case as it will often indicate which specific parameter or header is missing or misconstructed. Most error messages for Bad Request will be in the following format: Invalid Argument: Object.Property
  • 401 Unauthorized This response indicates that you did not provide a valid authentication method. Refer to the Authentication page to learn how to authenticate against the API. The most common reason behind a 401 response is providing an invalid or expired Bearer token. A 401 response is a good indication that it is time to generate a new token using the Refresh token.
  • 403 Forbidden This response indicates that you are not authorized to perform the requested operation. Permissions are an integral part of ShareFile, so proper access controls and admin roles will always be required for most operations. The error message will clarify why this operation was not allowed and if there are any Roles the authenticated user should have.
  • 404 Not Found This response indicates that the resource you attempted to retrieve does not exist. If an invalid api endpoint is requested, a Not Found response will be sent as well.
  • 429 Too Many Requests This response indicates that you have attempted too many requests or have exceeded a quota or threshold. The throttling is tied to a particular endpoint, usually login and reset password operations, so you should be able to perform other operations even when being blocked on the throttled request. The error message will indicate how long until the operation can be attempted again.
  • 500 Internal Server Error This response indicates that an unexpected error occurred while processing the request. Internal Server Errors should happen very scarcely, and can usually be attributed to brief system hiccups. Internal Server Errors are often out of your hands as a developer, with one exception: if the error message returned looks something like this, “Object reference not set to an instance of an object,” it usually means that the request’s JSON payload is misconstructed or that the Content-type header is not set to application/json. Please contact us if you get a persistent Internal Server error and the error message is not helpful.

Posting on the Developer's Forum

If you run out of options for troubleshooting an API issue, you can search the ShareFile Developer’s forum for help. ShareFile API developers monitor the site and can answer most of your questions and help you troubleshoot problems with the API. We also encourage you to browse the forum and answer any questions others may have. If you are posting on the forum about an API request that is failing, here are some things to keep in mind:

  • Before posting, use the Search option to see if your issue has already been reported and solved somewhere else.
  • When posting, try to include as much information as possible. Simply stating that you are having issue getting a request to work will usually not be enough. Please try to provide the following:
    • The response status code and error message
    • A trace or “dump” of the failed http request that contains the url, headers (remember to obfuscate any bearer token or session cookie), and JSON payload.
  • While we can help you achieve your use case using the API, we cannot implement any code for you. We strongly recommend the .NET and PowerShell SDK’s as they greatly simplify the process of developing with the API. If you don’t work in any of these languages, we also have several code samples that illustrate how to make ShareFile API requests in various languages.