Requests and responses
With the Hitachi API for Amazon S3, you submit requests for operations to HCP, and HCP returns responses that indicate the outcome of the request and include any requested information or content.
This section of the Help contains general information about S3 compatible requests and HCP responses to those requests.
Request line
The request line for an S3 compatible request specifies the operation to be performed and the version of HTTP on which the S3 compatible API is based. Additionally:
- If the target of the request is a tenant or if the target is a bucket and the hostname includes the bucket name, the request line includes a forward slash by itself.
For example, here are the request line and HOST header for a request to create a bucket named finance where the bucket name is included in the hostname:
PUT / HTTP/1.1 HOST: finance.europe.hcp.example.com
- If the target of the request is a bucket and the hostname does not include the bucket name, the request line includes the a forward slash followed by the bucket name.
For example, here are the request line and HOST header for a request to create a bucket named finance where the bucket name is not included in the hostname:
PUT /finance HTTP/1.1 HOST: europe.hcp.example.com
- If the target of the operation is an object, the request line includes a forward slash followed by the object name either by itself or following the bucket name, depending on whether the hostnames includes the bucket name.
For example, here are the request line and HOST header for a request to create an object named quarterly_rpts/Q4_2019 where the bucket name is included in the hostname:
PUT /quarterly_rpts/Q4_2019 HTTP/1.1 HOST: finance.europe.hcp.example.com
Here are the request line and HOST header for a request to create an object named quarterly_rpts/Q4_2019 in a bucket named finance where the bucket name is not included in the hostname:
PUT /finance/quarterly_rpts/Q4_2019 HTTP/1.1 HOST: europe.hcp.example.com
- If the request uses any query parameters, those parameters are appended to the last one of the items listed above.
For example, here are the request line and HOST header for a request to add an ACL to an object named quarterly_rpts/Q4_2019 where the bucket name is included in the hostname:
PUT /quarterly_rpts/Q4_2019?acl HTTP/1.1 HOST: finance.europe.hcp.example.com
If the request includes invalid query parameters, those parameters are ignored.
Common request headers
Some request headers are common to all S3 compatible API requests. The list below describes those headers. Request headers that are specific to certain requests are described in the sections for those requests.
Request header names are not case sensitive. Depending on the header, the header values may be case sensitive.
Authorization
Specifies user credentials or requests anonymous access.
Date
Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.
The date and time must always be specified using Greenwich Mean Time (GMT).
To specify the date and time, use this format:
DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
In this format:
DDD
The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
dd
The two-digit day of the month.
MMM
The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
yyyy
The four-digit year.
HH
The hour on a 24-hour clock.
mm
The number of minutes.
ss
The number of seconds.
For example:
Thu, 23 Mar 2017 14:27:05 +0000
All S3 compatible requests must include either a
Date
header or anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-amz-date
header.Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the
Date
header above.
Cache-Control
, Connection
, Content-Disposition
, Content-Encoding
, Content-Language
, and Pragma
. For more information about HTTP request headers, see the HTTP/1.1 standards (RFCs 7230 through 7237).x-amz-acl
Adds a canned ACL to the bucket.
This header is used only to add a canned ACL to a bucket. If you’re using individual
x-amz-grant-
headers to add the ACL, thex-amz-acl
header is invalid.x-amz-grant-full-control
Grants full control over the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-full-control
header is invalid.x-amz-grant-read
Grants the browse and read data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read
header is invalid.x-amz-grant-read-acp
Grants the read ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-read-acp
header is invalid.x-amz-grant-write
Grants the write and delete data access permissions for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write
header is invalid.x-amz-grant-write-acp
Grants the write ACL data access permission for the bucket to one or more specified grantees.
If you’re using a canned ACL to add an ACL to a bucket, the
x-amz-grant-write-acp
header is invalid.x-hcp-pretty-print
Optionally, requests that the XML response body be formatted for readability. Valid values are:
true
Format the XML response body for readability.
false
Do not apply any special formatting to the XML response body.
The default is false.
The values
true
andfalse
are not case sensitive.
Response status line
The status line returned in response to an S3 compatible request specifies the version of HTTP on which the S3 compatible API is based and an HTTP status code that indicates the outcome of the request. HTTP status codes in the 2xx range indicate that the requested operation was successful. HTTP status codes in the 3xx, 4xx, and 5xx ranges, typically indicate that an error occurred and HCP did not perform the requested operation.
Here’s an example of a response status line that indicates that the requested operation was successful:
HTTP/1.1 200 OK
Here’s an example of a response status line for an unsuccessful operation:
HTTP/1.1 409 Conflict
Common response headers
Some response headers are common to all S3 compatible API requests, while some are specific to certain requests. The table below describes some of the common response headers.
Content-Length
The size, in bytes, of the response body if HCP can determine the size before formulating the response.
If the response does not include a response body, the value of the
Content-Length
header is0
(zero).Content-Type
The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is
application/octet-stream
.Because HCP returns error information in a response body, the response to any request can include a
Content-Type
header.Date
The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:
DDD dd MMM yyyy HH:mm:ss GMT
For example:
Fri, 18 Sep 2020 14:27:05 GMT
Transfer-Encoding
Always
chunked
. This header is returned if the response includes a response body but HCP cannot determine the size of the response body before formulating the response.Because HCP returns error information in a response body, the response to any request can include a
Transfer-Encoding
header.
Some common response headers address browser security concerns. These headers have fixed values. The table below describes these headers.
Cache-Control
Specifies directives that must be obeyed by all caching mechanisms along the request/response chain
Values: no-cache, no-store, must-revalidate
Content-Security-Policy
Restricts the content that the browser can load to the sources specified by the header value
Values: default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'self'; frame-ancestors 'self';
Expires
Causes the response to become stale immediately after it is sent
Value: Thu, 01 Jan 1970 00:00:00 GMT
Pragma
Prevents the response from being used for subsequent requests for the same resource without the browser first checking whether the resource has changed
Value: no-cache
X-Content-Type-Options
Prevents the browser from examining the returned content to determine the content MIME type
Value: nosniff
X-DNS-Prefetch-Control
Prevents the browser from performing domain name resolution on URLs embedded in returned content before the URLs are requested
Value: off
X-Download-Options
Prevents the browser from opening resources that are downloaded through links in the returned content
Value: noopen
X-Frame-Options
Prevents the browser from rendering the returned content in a frame on a page containing content not returned by the HCP system
X-XSS-Protection
Stops the browser from loading the returned content if the browser detects reflected cross-site scripting (XSS) in the response
Values: 1; mode=block
For information about request-specific response headers, see the "Response header" topic for each type of operation you can perform with the S3 compatible API.
- HCP can also return several standard HTTP response headers that are not described in this book. Among others, these include
Connection
,Content-Disposition
,Content-Encoding
, and
. For more information about HTTP response headers, see the HTTP/1.1 standards (RFCs 7230 through 7237).Content-Language
- The
Cache-Control
andExpires
headers are not returned with error responses.
Error response body
When an S3 compatible request results in an error, HCP returns information about the error in an error request body. An error request body contains XML in this format:
<?xml version="1.0" encoding="UTF-8"?> <Error> <Code>error-code</Code> <Message>error-message</Message> <RequestId>request-id</RequestId> <HostId>host-id</HostId> <BucketName>specified-bucket-name</BucketName> <Key>object-name</Key> </Error>
The list below describes XML elements in an error response body.
Error
Root element.
Code
The error code.
Message
Text that provides more information about the error.
RequestId
The HCP-internal ID assigned to the request.
HostId
The HCP-internal ID of the host responding to the request.
BucketName
The specified bucket name. This element is included in the response body only when the error code is
NoSuchBucket
.Key
The specified object name. This element is included in the response body only when the error code is
NoSuchKey
.
Error codes
Every error response body contains an error code and a message that provides more information about the error. Error codes are returned in addition to HTTP status codes. A single HTTP status code can correspond to multiple error codes.
The table below describes the error codes that can be returned in response to S3 compatible API requests.
Status Code | Meaning | Error Code | Description |
200 | OK | BucketAlreadyOwnedByYou | You are trying to create a bucket, but a bucket with the specified name already exists and is owned by you. |
200 | OK | EntityTooSmall |
The list of parts in a request to complete a multipart upload includes a part, other than the last part, that is smaller than one megabyte. When this error occurs, the multipart upload is not completed, even though the returned status code is 200 (OK). |
200 | OK | InvalidPart |
One or more of the parts listed in a request to complete a multipart upload cannot be found. Either the part was not uploaded, or the specified ETag does not match the ETag for the uploaded part. When this error occurs, the multipart upload is not completed, even though the returned status code is 200 (OK). |
200 | OK | InvalidPartOrder |
The list of parts in a request to complete a multipart upload is not in ascending order by part number. When this error occurs, the multipart upload is not completed, even though the returned status code is 200 (OK). |
304 | Not Modified | PreconditionFailed |
HCP did not perform the requested operation because a specified precondition for the operation was not satisfied. When this error occurs with a request to complete a multipart upload, the returned status code is 200 (OK), but the multipart upload is not completed. |
400 | Bad Request | BadDigest |
One of these:
|
400 | Bad Request | InvalidArgument |
Possible reasons include:
|
400 | Bad Request | InvalidBucketName | The specified bucket name is invalid. |
400 | Bad Request | InvalidRequest |
You are trying to create a bucket, and one of these is true:
|
400 | Bad Request | KeyTooLong | The specified object name is too long. |
400 | Bad Request | MalformedXML |
The request is invalid. Possible reasons include:
|
400 | Bad Request | MetadataTooLarge | The custom metadata you are trying to store is larger than two kilobytes. |
400 | Bad Request | EntityTooLarge | Your proposed upload exceeds the maximum allowed object size. |
400 | Bad Request | InvalidDigest | The Content-MD5 you specified is not valid. |
400 | Bad Request | InvalidPolicyDocument | The content of the form does not meet the conditions specified in the policy document. |
400 | Bad Request | MalformedPOSTRequest | The body of your POST request is not well-formed multipart/form-data. |
400 | Bad Request | 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 | MissingSecurityHeader | Your request is missing a required header. |
400 | Bad Request | UserKeyMustBeSpecified | The bucket POST must contain the specified field name. If it is specified, check the order of the fields. |
403 | Forbidden | AccessDenied |
Possible reasons include:
|
403 | Forbidden | InvalidAccessKeyId | The access key provided in the request does not correspond to a valid user account. |
403 | Forbidden | InvalidObjectState | The operation is not valid for the current state of the object. |
403 | Forbidden | RequestTimeTooSkewed | The difference between the request time and the server's time is too large. |
404 | Not Found | NoSuchBucket | The specified bucket does not exist. |
404 | Not Found | NoSuchKey | HCP could not find an object with the specified name. |
404 | Not Found | NoSuchUpload | The specified multipart upload does not exist. Either the upload ID is invalid, or the multipart upload was aborted or completed. |
404 | Not Found | NoSuchLifecycleConfiguration | The lifecycle configuration does not exist. |
405 | Method Not Allowed | MethodNotAllowed | The requested HTTP method is not supported for the target tenant, bucket, or object. |
409 | Conflict | BucketAlreadyExists | You are trying to create a bucket, but a bucket with the specified name already exists and either is owned by a user other than you or has no owner. |
409 | Conflict | BucketNotEmpty | You are trying to delete a bucket that is not empty. |
409 | Conflict | InvalidBucketState | The target bucket does not currently support the requested operation. |
409 | Conflict | OperationAborted |
Possible reasons include:
|
411 | Length Required | MissingContentLength | You must provide the Content-Length HTTP header. |
412 | Precondition Failed | PreconditionFailed |
HCP did not perform the requested operation because a specified precondition for the operation was not satisfied. When this error occurs with a request to complete a multipart upload, the returned status code is 200 (OK), but the multipart upload is not completed. |
413 | Request Entity Too Large | OutOfSpace | The object you are trying to store or the custom metadata you are trying to add is too big for the amount of space left in the bucket. |
416 | Requested Range Not Satisfiable | InvalidRange |
You are trying to retrieve part of an object, and one of these is true:
|
500 | Internal Server Error | InternalError |
An internal error occurred. If this error persists, contact your tenant administrator. |
501 | Not Implemented | NotImplemented | The requested operation is not supported. |
503 | Service Unavailable | ServiceUnavailable |
HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator. |
403 | Forbidden | SignatureDoesNotMatch | The signature provided with the request does not match the request contents. Check that the secret key and signing method used are correct. |