Introduction

The IBM Cloud® Object Storage API is a REST-based API for reading and writing objects. It uses IBM Cloud® Identity and Access Management for authentication/authorization, and supports a subset of the S3 API for easy migration of applications to IBM Cloud.

For details about using Object Storage, see the IBM Cloud docs.

Object Storage is a global service. The location of data is determined by the region where a bucket is created, and subsequent requests to that bucket must be sent to the same corresponding endpoint. The examples shown here assume that requests are sent to the US South region. For more details about selecting endpoints Object Storage, see the IBM Cloud docs.

Java developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Java. For more information, see the COS SDK for Java API Reference.

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.cos</groupId>
  <artifactId>ibm-cos-java-sdk</artifactId>
</dependency>

GitHub

https://github.com/IBM/ibm-cos-sdk-java

JavaScript developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for JavaScript. For more information, see the COS SDK for JavaScript API Reference.

The SDK is supported on Node versions 4.x and later.

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-cos-sdk

GitHub

https://github.com/IBM/ibm-cos-sdk-js

Python developers can use this SDK to interact with Object Storage. The SDK is a fork of the boto3 library. For more information, see the COS SDK for Python API Reference.

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade ibm-cos-sdk

GitHub

https://github.com/IBM/ibm-cos-sdk-python

Go developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Go. For more information, see the COS SDK for Go API Reference.

The SDK supports Go versions 1.10 - 1.12.

The code examples on this tab use the client library that is provided for Go.

go get -u github.com/IBM/ibm-cos-sdk-go

GitHub

https://github.com/IBM/ibm-cos-sdk-go

Error handling

The Object Storage service uses standard HTTP response codes to indicate if a method completes successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

For more details about response codes Object Storage, see the IBM Cloud docs.

| Element | Type | Description | |-----------------------------|--------|--------------------------------------------------------------------------------| | Code | string | Error code identifying the type of error (for example NoSuchBucket, AccessDenied) | | Message | string | Human-readable error message describing what went wrong | | Method | string | HTTP method used in the request that caused the error (for example GET, PUT, DELETE) | | Resource | string | The S3 resource path that was accessed when the error occurred | | RequestId | string | Unique identifier for the request, used for troubleshooting and support | | StringToSign | string | The canonical string that was used for signature calculation in authentication | | StringToSignBytes | string | Hexadecimal representation of the StringToSign bytes | | SignatureProvided | string | The signature value provided by the client in the request | | CanonicalRequest | string | The canonical request string used in AWS Signature Version 4 authentication | | CanonicalRequestBytes | string | Hexadecimal representation of the CanonicalRequest bytes | | AWSAccessKeyId | string | The AWS access key ID used in the request authentication | | ArgumentName | string | Name of the invalid argument that caused the error | | ArgumentValue | string | Value of the invalid argument that caused the error | | HeadersNotSigned | string | List of headers that were not included in the signature calculation | | ResourceType | string | Type of S3 resource involved in the error (for example bucket, object) | | Key | string | Object key (name) associated with the error | | VersionId | string | Version ID of the object if versioning is enabled | | ProposedSize | string | Size value that was proposed in the request | | MinSizeAllowed | string | Minimum allowed size for the operation | | MaxSizeAllowed | string | Maximum allowed size for the operation | | PartNumber | string | Part number in a multipart upload operation | | ETag | string | Entity tag of the object involved in the error | | ClientComputedContentSHA256 | string | SHA256 hash of the content as computed by the client | | S3ComputedContentSHA256 | string | SHA256 hash of the content as computed by the S3 service | | httpStatusCode | int | HTTP status code associated with the error (for example 404, 403, 500) |

Note: Only Code, Message, RequestId, and httpStatusCode are required elements. All other elements are optional and included based on the specific error type and context.

Sample basic error response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Error>
    <Code>NoSuchKey</Code>
    <Message>The specified key does not exist.</Message>
    <Resource>/bucket/object</Resource>
    <RequestId>c786eaf9-c6f0-4aa5-bb57-604898497edb</RequestId>
    <httpStatusCode>404</httpStatusCode>
</Error>

Sample error response with illegal arguments:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Error>
    <Code>InvalidArgument</Code>
    <Message>Provided max-keys not an integer or within integer range</Message>
    <Resource>/bucket/</Resource>
    <RequestId>e0fc367e-dcd3-4c03-9684-981116501c25</RequestId>
    <ArgumentName>max-keys</ArgumentName>
    <ArgumentValue>invalid-value</ArgumentValue>
    <httpStatusCode>400</httpStatusCode>
</Error>

Error codes

| Error Code | Description | HTTP Status Code | |-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| | AccessDenied | Access Denied | 403 Forbidden | | BadDigest | The Content-MD5 that you specified did not match what we received. | 400 Bad Request | | BucketAlreadyExists | The requested bucket name isn't available. The bucket namespace is shared by all users of the system. Please select a different name and try again. | 409 Conflict | | BucketAlreadyOwnedByYou | Your previous request to create the named bucket that is succeeded and you already own it. | 409 Conflict | | BucketNotEmpty | The bucket that you tried to delete isn't empty. | 409 Conflict | | CredentialsNotSupported | This request does not support credentials. | 400 Bad Request | | EntityTooSmall | Your proposed upload is smaller than the minimum allowed object size. | 400 Bad Request | | EntityTooLarge | Your proposed upload exceeds the maximum allowed object size. | 400 Bad Request | | IncompleteBody | You did not provide the number of bytes specified by the Content-Length HTTP header. | 400 Bad Request | | IncorrectNumberOfFilesInPostRequest | POST requires exactly one file upload per request. | 400 Bad Request | | InlineDataTooLarge | Inline data exceeds the maximum allowed size. | 400 Bad Request | | InternalError | We encountered an internal error. Please try again. | 500 Internal Server Error | | InvalidAccessKeyId | The AWS access key Id that you provided does not exist in our records. | 403 Forbidden | | InvalidArgument | Invalid Argument | 400 Bad Request | | InvalidBucketName | The specified bucket is not valid. | 400 Bad Request | | InvalidBucketState | The request is not valid with the current state of the bucket. | 409 Conflict | | InvalidDigest | The Content-MD5 that you specified is not valid. | 400 Bad Request | | InvalidLocationConstraint | The specified location constraint is not valid. For more information about regions, see How to Select a Region for Your Buckets. | 400 Bad Request | | InvalidObjectState | The operation is not valid for the current state of the object. | 403 Forbidden | | InvalidPart | One or more of the specified parts might not be found. The part might not have been uploaded, or the specified entity tag might not have matched the part's entity tag. | 400 Bad Request | | InvalidPartOrder | The list of parts was not in ascending order. Parts list must specified in order by part number. | 400 Bad Request | | InvalidRange | The requested range cannot be satisfied. | 416 Requested Range Not Satisfiable | | InvalidRequest | Please use AWS4-HMAC-SHA256. | 400 Bad Request | | InvalidSecurity | The provided security credentials are not valid. | 403 Forbidden | | InvalidURI | Mightn't parse the specified URI. | 400 Bad Request | | KeyTooLong | Your key is too long. | 400 Bad Request | | MalformedPOSTRequest | The body of your POST request is not well-formed multipart/form-data. | 400 Bad Request | | MalformedXML | The XML you provided was not well-formed or did not validate against our published schema. | 400 Bad Request | | MaxMessageLengthExceeded | Your request was too large. | 400 Bad Request | | MaxPostPreDataLengthExceededError | Your POST request fields preceding the upload file were too large. | 400 Bad Request | | MetadataTooLarge | Your metadata headers exceed the maximum allowed metadata size. | 400 Bad Request | | MethodNotAllowed | The specified method is not allowed against this resource. | 405 Method Not Allowed | | MissingContentLength | You must provide the Content-Length HTTP header. | 411 Length Required | | MissingRequestBodyError | This happens when the user sends an empty xml document as a request. The error message is, "Request body is empty." | 400 Bad Request | | NoSuchBucket | The specified bucket does not exist. | 404 Not Found | | NoSuchKey | The specified key does not exist. | 404 Not Found | | NoSuchUpload | The specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed. | 404 Not Found | | NotImplemented | A header that you provided implies functionality that is not implemented. | 501 Not Implemented | | OperationAborted | A conflicting conditional operation is currently in progress against this resource. Try again. | 409 Conflict | | PreconditionFailed | At least one of the preconditions you specified did not hold. | 412 Precondition Failed | | Redirect | Temporary redirect. | 307 Moved Temporarily | | RequestIsNotMultiPartContent | Bucket POST must be of the enclosure-type multipart/form-data. | 400 Bad Request | | RequestTimeout | Your socket connection to the server was not read from or written to within the timeout period. | 400 Bad Request | | RequestTimeTooSkewed | The difference between the request time and the server's time is too large. | 403 Forbidden | | ServiceUnavailable | Reduce your request rate. | 503 Service Unavailable | | SlowDown | Reduce your request rate. | 503 Slow Down | | TemporaryRedirect | You are being redirected to the bucket while DNS updates. | 307 Moved Temporarily | | TooManyBuckets | You have attempted to create more buckets than allowed. | 400 Bad Request | | UnexpectedContent | This request does not support content. | 400 Bad Request | | UserKeyMustBeSpecified | The bucket POST must contain the specified field name. If it is specified, check the order of the fields. | 400 Bad Request |

Cloud Object Storage S3 API | IBM Cloud API Docs