Skip to main content
Hitachi Vantara Knowledge

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 an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-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.

NoteHCP accepts but does not process several standard HTTP request headers. Among others, these include 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).
Common but not required
  • 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, the x-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 and false 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 is 0 (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.

Note
  • 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 Content-Language. For more information about HTTP response headers, see the HTTP/1.1 standards (RFCs 7230 through 7237).
  • The Cache-Control and Expires 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 CodeMeaningError CodeDescription
200OKBucketAlreadyOwnedByYouYou are trying to create a bucket, but a bucket with the specified name already exists and is owned by you.
200OKEntityTooSmall

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).

200OKInvalidPart

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).

200OKInvalidPartOrder

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).

304Not ModifiedPreconditionFailed

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.

400Bad RequestBadDigest

One of these:

  • The value of the Content-MD5 header does not match the Base64-encoded 128-bit MD5 hash of the submitted data.
  • The value of the Content-MD5 header is not a valid hash value.
400Bad RequestInvalidArgument

Possible reasons include:

  • A query parameter has an invalid value.
  • An ACL grant header specifies an invalid grantee.
  • The request includes conflicting conditional headers (for example, If-Match and If-None-Match).
  • The request includes a header that is invalid for the requested operation.
400Bad RequestInvalidBucketNameThe specified bucket name is invalid.
400Bad RequestInvalidRequest

You are trying to create a bucket, and one of these is true:

  • You already own the maximum number buckets allowed per user.
  • The tenant does not have enough space for another bucket.
  • The tenant already has the maximum number of buckets it’s allowed to have.
  • An unexpected error occurred.
400Bad RequestKeyTooLongThe specified object name is too long.
400Bad RequestMalformedXML

The request is invalid. Possible reasons include:

  • The object name specified in the request is invalid.
  • A query parameter specifies an invalid value.
  • The request includes both the x-amz-acl header and an individual ACL grant header.
  • The XML in the request body is malformed or contains an invalid value.
400Bad RequestMetadataTooLargeThe custom metadata you are trying to store is larger than two kilobytes.
400Bad RequestEntityTooLargeYour proposed upload exceeds the maximum allowed object size.
400Bad RequestInvalidDigestThe Content-MD5 you specified is not valid.
400Bad RequestInvalidPolicyDocumentThe content of the form does not meet the conditions specified in the policy document.
400Bad RequestMalformedPOSTRequestThe body of your POST request is not well-formed multipart/form-data.
400Bad RequestMissingRequestBodyErrorThis happens when the user sends an empty xml document as a request. The error message is, "Request body is empty."
400Bad RequestMissingSecurityHeaderYour request is missing a required header.
400Bad RequestUserKeyMustBeSpecifiedThe bucket POST must contain the specified field name. If it is specified, check the order of the fields.
403ForbiddenAccessDenied

Possible reasons include:

  • You do not have permission to perform the requested operation.
  • The requested operation requires authenticated access, and you have not provided valid user account credentials.
  • The user account identified by the access key provided in the request is disabled. To have the account enabled, contact your tenant administrator.
  • The target bucket does not currently support the requested operation.
  • The tenant does not currently support most S3 compatible operations on buckets.
  • You are using a presigned URL, and the time period during which the URL was valid has expired.
403ForbiddenInvalidAccessKeyIdThe access key provided in the request does not correspond to a valid user account.
403ForbiddenInvalidObjectStateThe operation is not valid for the current state of the object.
403ForbiddenRequestTimeTooSkewedThe difference between the request time and the server's time is too large.
404Not FoundNoSuchBucketThe specified bucket does not exist.
404Not FoundNoSuchKeyHCP could not find an object with the specified name.
404Not FoundNoSuchUploadThe specified multipart upload does not exist. Either the upload ID is invalid, or the multipart upload was aborted or completed.
404Not FoundNoSuchLifecycleConfigurationThe lifecycle configuration does not exist.
405Method Not AllowedMethodNotAllowedThe requested HTTP method is not supported for the target tenant, bucket, or object.
409ConflictBucketAlreadyExistsYou 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.
409ConflictBucketNotEmptyYou are trying to delete a bucket that is not empty.
409ConflictInvalidBucketStateThe target bucket does not currently support the requested operation.
409ConflictOperationAborted

Possible reasons include:

  • HCP cannot perform the requested operation because a conflicting operation is already in progress.
  • You are trying to delete an object that is under retention.
  • You are trying to create an object with the same name as an existing object, and versioning is disabled.
  • You are trying to read, add an ACL to, or delete an object that is currently being written to the bucket.
411Length RequiredMissingContentLengthYou must provide the Content-Length HTTP header.
412Precondition FailedPreconditionFailed

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.

413Request Entity Too LargeOutOfSpaceThe 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.
416Requested Range Not SatisfiableInvalidRange

You are trying to retrieve part of an object, and one of these is true:

  • The specified start position is greater than the size of the requested data.
  • The size of the specified range is zero.
500Internal Server ErrorInternalError

An internal error occurred.

If this error persists, contact your tenant administrator.

501Not ImplementedNotImplementedThe requested operation is not supported.
503Service UnavailableServiceUnavailable

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.

403ForbiddenSignatureDoesNotMatchThe signature provided with the request does not match the request contents. Check that the secret key and signing method used are correct.

 

  • Was this article helpful?