Contents x
Partner API Error Handling and Status Codes
    • Print
    • Dark
      Light
    Contents

    Partner API Error Handling and Status Codes

      • Print
      • Dark
        Light
      Article summary

      For all of the Backblaze API operations and their corresponding documentation, see API Documentation.

      The following status codes and error messages may be returned in Backblaze B2 Cloud Storage Partner API responses.

      Status Codes

      For all calls to the Partner API, 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" intended only for humans.

      A status of 200 (OK) means success. Any code in the 400 or 500 range is a failure. See Error Handling for details. At present, the Partner API does not use redirects (status codes in the 300 range).

      Error Handling

      Failures to connect to the Backblaze servers, and networking problems in general can cause errors, which are reported in the normal way.

      If you get a response from the Partner API, the HTTP status code will tell you whether it is an error or not. A 200-series status code, such as 200 (OK), or 204 (No Content), means that the call was successful. For most calls, a successful response will have status 200 and contain the JSON that is described in the API documentation. A 204 status code indicates that the call was successful, but there is no JSON content in the response. Any code outside the 200-series is an error, and the response will contain a JSON error structure indicating what went wrong. 

      HTTP Status Codes

      The documentation for each API includes information on specific errors returned for that API; 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.
      204The request was successful, and the response is empty.
      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.
      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.
      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.
      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.
      408REQUEST TIMEOUT
      The service timed out trying to read your request.
      429TOO MANY REQUESTS
      Backblaze B2 may limit API requests on a per-account basis. For more information on rate limits, please refer to our guide.
      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_group_id",
    "message" : "group Id is invalid or is not authorized"
}
      Was this article helpful?
      Related articles
      What's Next