Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

 

Table of Contents
maxLevel2

SUCCESS

Info
titleVersioning

We will maintain collections of existing fields as well as their format through the complete lifecycle of version 1 of the API. However, the API is still in BETA and from time to time we may need to extend existing endpoints by introduction of new fields to keep them up to date with improvements to Fitbit platform. We definitely will announce such changes on this wiki and in Fitbit API Dev Forum before they go into production release. Still, keep in mind that best practice for your application's response parser would be to stay loose and don't fail validation if it sees extra fields.

...

Status code:

204 No Content (DELETE requests), 201 Created (POST requests)

Content-Type:

text/xml or application/json

Body:

Empty body

Response - with Data

When the response returns data in addition to a status code, the body contains the data.

Status code:

200 OK (GET/POST requests), 201 Created (POST requests)

Content-Type:

text/xml or application/json

Body:

Response in the format requested: JSON or XML

Response Body Format

JSON:

Code Block

{
    <data>
}

XML: 

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<result>
    [data]
</result>

...

Status code:

400 Bad Request, 401 Unauthorized, 404 Not Found, 409 Conflict

Content-Type:

application/x-www-form-urlencoded

Body:

Error response body in the format requested: JSON or XML

 

Errors:

400 Bad Request

Any case where either endpoint doesn't exist, resource path parameters are invalid, POST request parameters are invalid or no Authentication header provided. This doesn't include invalid specific resource ids

401 Unauthorized

The OAuth Authorization header provided and is invalid (consider looking in response body). Client or authorized user have no privilege to view requested data (for example, requested resource's owner has privacy permission "You" or "Friends" for requested resource)

404 Not Found

The resource with given id doesn't exist

409 Conflict

Either you hit the rate limiting quota for the client or for the viewer, or you trying to create conflicting resources (consider looking at errorType)

500 Internal Server Error

Something is terribly wrong on our side (and we are working on it). Try your request later

502 Bad GatewayWe will be back soon. Maintenance!

 

Also, in most cases additional details are provided in the response body via errorType element:

validation

Either resource path parameters or POST parameters are invalid (fieldName should help identify the problem)

oauthoAuth message verification errors (invalid signature, expired access token, etc)

request

Client or authorized user have no privilege to view requested data. This is also the errorType for rate limiting

not_found

The resource with given id doesn't exist

system

Something is terribly wrong on our side (and we are working on it). Try your request later

...

Note: Text within <> is a descriptive place holder for a value or repeated elements.

Code Block

{
    "errors":[
        {
            "errorType":<value>,
            "fieldName":<value>,
            "message":<value>
        }
    ]
} 

...

Note: Text within [] is a descriptive place holder for a value or repeated elements.

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<result>
    <errors>
        <apiError>
            <errorType>[value]</errorType>
            <fieldName>[value]</fieldName>
            <message>[value]</message>
        </apiError>
    </errors>
</result>

Response Examples

JSON:

Code Block

{
    "errors":[
        {
            "errorType":"validation",
            "fieldName":"date",
            "message":"Invalid date: ABCD-EF-GH"
        }
    ]
} 

XML:

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<result>
    <errors>
        <apiError>
            <errorType>validation</errorType>
            <fieldName>date</fieldName>
            <message>Invalid date: ABCD-EF-GH</message>
        </apiError>
    </errors>
</result>

Defined oAuth Error Responses

ApiError-like formatted responses

Error response fieldsAdditional data
codeError typeField nameMessageoAuth versionWhen occurs
400oauthn/aNo Authorization header provided in the request. Each call to Fitbit API should be OAuth signed1.0 
401oauthoauth_consumer_keyInvalid consumer_key: <value>1.0when consumer key is empty or not found in db
401oauthoauth_access_tokenInvalid/expired user token: <value>1.0when "token" validation is required and access token value is empty
401oauthoauth_access_tokenThis endpoint should be signed with user's access token and secret1.0when "token" validation is required and access token provided but not found in db
401oauthoauth_access_tokenInvalid signature <signature_value> or token <token_value>1.0

when just "client" validation is required but signature does not match and access token provided

401oauthoauth_signatureInvalid signature: <value>1.0

1) when just "client" validation is required but no acces token provided and signature does not match

2) when "token" validation is required but signature does not match

401oauthoauth_timestampoauth_problem=timestamp_refused1.0timestamp validation failed but no "oauth_acceptable_timestamps" returned by validator
401oauthoauth_timestampoauth_acceptable_timestamps=<value>1.0timestamp validation failed and "oauth_acceptable_timestamps" returned by validator
401oauthoauth_nonceoauth_problem=nonce_used1.0nonce_used error of the oauth validator
401oauthoauth_signature_methodInvalid signature method: <value> Fitbit API currently supports: HMAC-SHA11.0unsupported signature method passed
401oauthn/a<form_encoded_oauth_validator_output_parameters>1.0other oAuth validator errors
400requestn/aYou should be partner to make this call1.0calls for features/resources designed for internal use
400requestn/aThis request should use https protocol1.0non-secure request for resource which was configured only for ssl-encrypted access
400requestn/aRead-only API client is not authorized to update resources1.0Client trying to get write access to "read-only" resource
400validationresource ownerGhost user! Please, provide valid user id in the resource path. Received: <value>1.0Invalid (not properly formatted) user id provided as part of request uri is invalid (when trying to request some other user's data, not the one who authorized the client)
      

Responses with different formatting

Response dataAdditional data
Http codeFormat descriptionResponse dataoAuth versionWhen occurs
400

contentType=application/x-www-form-urlencoded;charset=UTF-8

WWW-Authenticate header set as an example

OAuth request to invalid domain: <domain>1.0request to non api domain