Request / Response Formats

All bitly APIs support an optional return format parameter format=json. Note that json is the default response format. but xml is also available. Some endpoints also support a simple txt format.

All bitly APIs support jsonp which is the json format with a callback specified, such as:

format=json&callback=*callback_method*

• All API requests should be against the domain api.bitly.com or api-ssl.bitly.com (see examples).

• HTTP Response Status Code is 200 on all valid response in json and xml formats. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid.

• For txt format calls, the HTTP Response Status Codes are used to indicate a problem with the request, rate limiting, or other errors. The response body will be equivalent to status_txt in json and xml calls for all non 200 response codes.

• The status_code is 200 for a successful request, 403 when rate limited, 503 for temporary unavailability, 404 to indicate not-found responses, and 500 for all other invalid requests or responses.

• status_txt will be a value that describes the nature of any error encountered. Common values are RATE_LIMIT_EXCEEDED, MISSING_ARG_%s to denote a missing URL parameter, and INVALID_%s to denote an invalid value in a request parameter (where %s is substituted with the name of the request parameter).

Example Outputs:

• json { "status_code": 200, "status_txt": "OK", "data" : ... }
• json { "status_code": 403, "status_txt": "RATE_LIMIT_EXCEEDED", "data" : null }
• json { "status_code": 500, "status_txt": "INVALID_URI", "data" : null }
• json { "status_code": 500, "status_txt": "MISSING_ARG_LOGIN", "data" : null }
• json { "status_code": 503, "status_txt": "UNKNOWN_ERROR", "data" : null }
• jsonp callback_method({ "status_code": 200, "status_txt": "OK", "data" : ... })

• xml

  <?xml version="1.0" encoding="UTF-8"?>
  <response>
       <status_code>200</status_code>
       <status_txt>OK</status_txt>
       <data>
           ...
       </data>
  </response>