Contents x
Introduction
    • Print
    • Dark
      Light
    Contents

    Introduction

      • Print
      • Dark
        Light
      Article Summary

      The Native API can be used to access functionality, such as application key management and lifecycle rules.

      For more information about the B2 Native API and specific how-to guides, click here.

      Using the Backblaze Native API, you can:

      • Upload, download, and delete files
      • Create and manage the buckets that hold files
      • Manage the configuration of your account*

      * Backblaze B2 Native APIs only

      Prerequisites

      To get started, you will need to have "B2 Cloud Storage" enabled in your account settings. For detailed instructions, check out the Getting Started guide here.

      Authentication

      The Native API uses application keys to authenticate requests. Please refer to our guide on creating and using application keys for more information.

      API Base URL

      The base URL that you will use for most of the B2 Native API operations is returned by the b2_authorize_account call. The base URL looks similar to https://apiNNN.backblazeb2.com with NNN being the cluster number containing your account. For information about constructing the API URL, see Call the B2 Native API.

      Request and Response Formats

      The following request and response values are possible using the Native API.

      Status Codes

      For all calls to Backblaze B2 Cloud Storage, the HTTP status code that is returned indicates success or failure. Unsuccessful calls return a JSON error structure in the body of the response that includes the status: a "code" that is a short string and a "message" that is intended only for humans.

      A status of 200 (OK) means success, and 206 (Partial Content) means success when downloading using the Range header. Any code in the 400 or 500 range is a failure. At present, Backblaze B2 does not use redirects (status codes in the 300 range).

      Error Structure

      Failures to connect to the Backblaze B2 servers and networking problems in general can cause errors, which are reported in a standard format.

      If you receive a response from Backblaze B2, the HTTP status code tells you whether it is an error. A status of 200 (OK) means that the call was successful. For most calls, a successful response contains the JSON that is described in the API documentation. Any code other than 200 is an error, and the response contains a JSON error structure indicating what went wrong. The documentation for each API includes information on the specific errors that are returned for that API; the general classes of errors are as follows:

      HTTP Status Codes

      The general classes of errors are included in the following table:

      200The request was successful, and the response contains the JSON structure described in the page for the call.
      400BAD REQUEST
      There is a problem with a passed in request parameters - the JSON error structure returned will contain an error code of bad_request and a human-readable error message describing the problem.
      401UNAUTHORIZED

      When calling b2_authorize_account, this means that there was something wrong with the applicationKeyId or with the application key that was provided. The code unauthorized means that the application key is bad. The code unsupported means that the application key is only valid in a later version of the API.

      When uploading data using b2_upload_file or b2_upload_part, this can mean a variety of things. Try calling b2_get_upload_url or b2_get_upload_part_url again to get a new upload target and auth token. That call will either work or provide a meaningful error code.

      For all other API calls, the code returned tells you what to do. The code unauthorized means that the auth token is valid, but does not allow you to make this call with these parameters. When the code is either bad_auth_token or expired_auth_token you should call b2_authorize_account again to get a new auth token.

      403FORBIDDEN
      You have a reached a storage cap limit, or account access may be impacted in some other way; see the human-readable message.
      408REQUEST TIMEOUT
      The service timed out trying to read your request.
      429TOO MANY REQUESTS
      B2 may limit API requests on a per-account basis.
      500INTERNAL ERROR
      An unexpected error has occurred.
      503SERVICE UNAVAILABLE
      The service is temporarily unavailable. The human-readable message identifies the nature of the issue, in general we recommend retrying with an exponential backoff between retries in response to this error.

      For more detailed information on handling errors, see the Integration Checklist.

      JSON Error Structure

      statusThe numeric HTTP status code. Always matches the status in the HTTP response.
      codeA single-identifier code that identifies the error.
      messageA human-readable message, in English, indicating what went wrong.

      The following example shows a JSON error response:

      {
    "status" : 400,
    "code" : "invalid_bucket_name",
    "message" : "bucket name is too long"
}

      API Versions

      The current version is v3.

      Please refer to API Versions for more detailed information about API version history, including breaking changes and compatibility notes.

      Was this article helpful?
      What's Next