- Print
- DarkLight
Native API Error Handling and Status Codes
- Print
- DarkLight
The following status codes and error messages may be returned in Backblaze B2 Cloud Storage Native API responses.
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:
200 | The request was successful, and the response contains the JSON structure described in the page for the call. |
400 | BAD 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. |
401 | UNAUTHORIZED When calling When uploading data using For all other API calls, the code returned tells you what to do. The code |
403 | FORBIDDEN You have a reached a storage cap limit, or account access may be impacted in some other way; see the human-readable message. |
408 | REQUEST TIMEOUT The service timed out trying to read your request. |
429 | TOO MANY REQUESTS B2 may limit API requests on a per-account basis. |
500 | INTERNAL ERROR An unexpected error has occurred. |
503 | SERVICE 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
status | The numeric HTTP status code. Always matches the status in the HTTP response. |
code | A single-identifier code that identifies the error. |
message | A 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"
}