Error Handling
chevron down
 

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

HTTP Status Code Description
200 OK The request was successful.
201 Created The request was successful and a new resource was created.
204 No Content The request was successful and no response is provided.

4xx CLIENT ERRORS

HTTP Status Code Description
400 Bad Request Any case where either the endpoint doesn't exist, resource path parameters are invalid, POST request parameters are invalid or no Authentication header is provided. This doesn't include invalid specific resource ids.
401 Unauthorized The OAuth Authorization header provided is invalid (consider looking in response body). Client or authorized users have no privilege to view requested data (for example, requested resource's owner has privacy permission "You" or "Friends" for requested resource).
403 Forbidden The application is not authorized to access this resource.
404 Not Found The resource with given id doesn't exist.
409 Conflict The application tried to create a conflicting resources (consider looking at errorType).
411 Length Required POST requests require a content-length header field containing the anticipated size of the payload body.
429 Too Many Requests The application hit the rate limiting quota for the client or for the viewer.

5xx SERVER ERRORS

HTTP Status Code Description
500 Internal Server Error Something is wrong on our side (and we are working on it). Try your request later.
502 Bad Gateway We will be back soon. Maintenance!
503 Service Unavailable The Fitbit service is temporarily offline for maintenance. We'll be back soon.
504 Gateway Timeout The server did not get a response in time to complete the request.

Types of Errors

errorType Description
authorization The authorization failed.
expired_token The OAuth token has expired.
insufficient_permissions The application has insufficient permissions to the resource.
insufficient_scope The application is missing a scope.
invalid_client The client_id provided is invalid.
invalid_grant The grant_type value provided is invalid.
invalid_request The request syntax provided is invalid.
invalid_scope The scope provided is invalid.
invalid_token The OAuth token provided is invalid.
not_found The resource with given id doesn’t exist.
oauth OAuth token is invalid, missing or expired.
request The API request failed.
system The system request failed.
unsupported_grant_type The grant_type provided is invalid.
unsupported_response_type The response_type provided is invalid.
validation Request parameter is invalid or missing.

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://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"
                        }
                      ]
                    }