There are two ways to download files. b2_download_file_by_id, is used to download a file, given you have the file id, and b2_download_file_by_name using the file name. Both APIs only download one file at a time.

Applications intending to use the RANGE header to multithread the download of files can use the more efficient HEAD request to fetch file information, as opposed to making an initial call to download a single byte.

Some buckets may be private and require you to have an authorization token to access files, see b2_authorize_account. Alternatively, you can use b2_get_download_authorization as an authorization token to access files with a specific filename prefix.

Errors returned from b2_download_file_by_id and b2_download_file_by_name are usually because of a bad request, or because the request is unauthorized. Another cause of these errors is that the file was previously deleted and so can no longer be found.

400 Bad Request
- bad_request - message will describe the problem
401 Unauthorized
- missing_auth_token - there is no Authorization header
- bad_auth_token - the authorization token is not valid
- expired_auth_token - the authorization token had expired
- unauthorized - the auth token used does not allow access to this file
404 Not Found
- not_found - the bucket or file does not exist
416 Range Not Satisfiable
- range_not_satisfiable - the request is outside the size of the file content
429 Too Many Requests
- too_many_requests - your account has too many concurrent downloads
5xx
- There is a problem in the service. Retry with exponential back-off.

Downloading in Parallel

The URL and authorization token that you get from b2_authorize_account can be used by multiple downloading threads. You can download in parallel to increase overall throughput.

Cache-Control Policies

B2 allows you to configure Cache-Control policies on a bucket level. During the creation of a bucket or when updating a bucket, you can configure the policy by setting the Cache-Control policy in the Bucket Info. For general information about Bucket Info, see Buckets.

When setting the policy the key must be Cache-Control, which is case-sensitive.

Below is a java example of b2_create_bucket, where we set the cache policy for the bucket.

import java.io.*;
import java.util.*;
import java.net.HttpURLConnection;
import java.net.URL;

String apiUrl = ""; // Provided by b2_authorize_account
String accountId = ""; // Obtained from your B2 account page.
String accountAuthorizationToken = "";  // Provided by b2_authorize_account
HttpURLConnection connection = null;

try {
    URL url = new URL(apiUrl + "/b2api/v2/b2_create_bucket");
    connection = (HttpURLConnection)url.openConnection();
    connection.setRequestMethod("POST");
    connection.setRequestProperty("Authorization", accountAuthorizationToken);
    connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
    connection.setRequestProperty("charset", "utf-8");
    connection.setRequestProperty("Content-Length", Integer.toString(postData.length));
    connection.setDoOutput(true);
    DataOutputStream writer = new DataOutputStream(connection.getOutputStream());
    writer.write(
    "{" +
        "\"accountId\":\"" + accountId + "\"," +
        "\"bucketName\":\"photos\",
        \"bucketType\":\"allPrivate\",
        \"bucketInfo\": {\"Cache-Control\":\"max-age=600\"}"
    + "}"
        .getBytes(StandardCharsets.UTF_8));
} catch (Exception e) {
    e.printStackTrace();
} finally {
    connection.disconnect();
}

Upon downloading a file, the Cache-Control response header will be set according to the Cache-Control policy in the Bucket Info. If the bucket has no Cache-Control policy setting, then the default behavior is determined by the creation time of the bucket. All buckets created on or after September 8, 2021 have no default Cache-Control header included with file downloads. Any buckets created before September 8, 2021 have a default Cache-Control header value of "max-age=0, no-cache, no-store". The bucket's Cache-Control policy setting (or default behavior) may also be overridden on a per-file basis by specifying the X-Bz-Info-b2-cache-control header at file upload time (see b2_upload_file).