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 400 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).

  • If the status_code is not 200, only status_code and status_txt are guaranteed to be present and valid.

Example Outputs:

  • json { "status_code": 200, "status_txt": "OK", "data" : ... }
  • json { "status_code": 400, "status_txt": "MISSING_ARG_LOGIN", "data" : null }
  • json { "status_code": 403, "status_txt": "RATE_LIMIT_EXCEEDED", "data" : null }
  • json { "status_code": 500, "status_txt": "UNKNOWN ERROR", "data" : null }
  • json { "status_code": 503, "status_txt": "TEMPORARILY_UNAVAILABLE", "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>