Error Handling

The Fitbit Web API response will contain an HTTP status code which states if the endpoint executed successfully or failed. If an error occurs, the HTTP status code and response body can help clarify the cause of the failure. An attempt is made to use the appropriate HTTP codes whenever possible. The response body's errorType and message elements will provide more information about the exact problem. The status codes and error types are described below. See Error Messages for details on the specific errors.

Types of Status Codes

2xx SUCCESS

4xx CLIENT ERRORS

5xx SERVER ERRORS

Types of Errors

OAuth2 Errors

Authorization Request Errors

According to the OAuth 2.0 RFC, if the redirect_uri is valid, the user is redirected to the application's redirect_uri, and any errors are appended to the URI as a query string. However, this behavior could be used in a phishing attack. Therefore, Fitbit’s OAuth 2.0 implementation diverges from the spec in that the user will remain on https://www.fitbit.com/oauth2/authorize , and any errors will be displayed on the page.

All OAuth2 errors, excluding the Authorization Request Errors, will be suffixed with:

"Visit https://dev.fitbit.com/reference/web-api/oauth2 for more information on the Fitbit Web API authorization process."

Like so:

{
  "errors": [
    {
      "errorType": "invalid_request",
      "message": "Missing parameters: refresh_token. Visit https://dev.fitbit.com/reference/web-api/oauth2 for more information on the Fitbit Web API authorization process."
    }
  ],
  "success": false
}

Access Token Request Errors

401 Unauthorized errors will occur when the "Authorization" header is invalid or missing. In addition to an "errors" JSON object, the API will respond with a WWW-Authenticate header and value of Basic realm="api.fitbit.com". However, if the API cannot determine the authentication scheme due to the Authorization header missing or the word "Basic" being misspelled, the WWW-Authenticate header will return the value Bearer realm="api.fitbit.com".

Refresh Token Request Errors

For 401 Unauthorized errors that occur during a refresh token request, the API will respond with a WWW-Authenticate header and a value of Bearer realm="api.fitbit.com", rather than a value of Basic realm="[redirect_uri]".

On rare occasions, the application may encounter a 409 Conflict error for concurrent refresh token requests. The avoid this error, applications should avoid making multiple, concurrent refresh token requests. Verify the refresh token process was not started for the same token more than once, and, where applicable, coordinate refresh token requests across processes.

Example

URL

GET https<nolink>://api.fitbit.com/1/user/-/activities/date/ABCD-EF-GH.json

Error Response Body

Status code:        400
Status message:     Bad Request
Response body:
                    { "errors": [
                        {
                          "errorType": "validation",
                          "fieldName": "date",
                          "message": "Invalid date:ABCD-EF-GH"
                        }
                      ]
                    }

HTTP Status Codes