REST API Introduction
  • 26 Jul 2022
  • PDF

REST API Introduction

  • PDF


Host Designation

Wasabi supports both the path-style and virtual-style requests available with AWS S3. A different host name is required (for example, s3.wasabisys.com versus s3.amazonaws.com). Wasabi recommends using path-style requests as shown in all examples in this guide (for example, http://s3.wasabisys.com/my-bucket/my-object) because the path-style offers the greatest flexibility in bucket names, avoiding domain name issues.

Error Responses

Where possible, Wasabi utilizes the exact error responses given by AWS S3. Some additional error codes are provided for additional functionality in Wasabi.

HTTP Error Codes

Error CodeWasabi DescriptionHTTP Status Code
UnavailableTemporarily unavailable503
UnrecoverableDataUnrecoverable
NotImplementedNot Implemented501
DBEntityNotfoundNo such entity404
DBEntityFoundEntityAlreadyExists409
DisconnectErrorConnectionClosed410
StatusInternalServerErrorInternalError, We encountered an internal error. Please contact customer support.500
StatusForbiddenAccessDenied403
AccessForbidden
AccountNotActivated
AccountProblem
AuthenticationLockout, There have been too many attempts to access the account with the wrong credentials. Please try again in five minutes.
InvalidAccessKeyId, The AWS Access Key Id you provided does not exist in our records.
InvalidAuthenticationCode, Authentication code for device is not valid.
RequestTimeTooSkewed, The difference between the request time and the current time is too large.
InvalidObjectState, The operation is not valid for the current state of the object.
StatusBadRequestAuthorizationHeaderMalformed400
AuthorizationQueryParametersError
BadDigest, The Content-MD5 you specified did not match what we received.
BadRequest, An error occurred when parsing the HTTP request.
IncompleteSignature, Request must contain a signature that conforms to AWS standards.
InvalidAction
InvalidArgument
InvalidDigest, The Content-MD5 you specified was invalid.
InvalidInput
InvalidParameterValue, An invalid or out-of-range value was supplied for the input parameter.
InvalidRequest
MalformedPolicy
MalformedPolicyDocument
PasswordPolicyViolation
ValidationError
XAmzContentSHA256Mismatch, The provided 'x-amz-content-sha256' header does not match what was computed.
EncryptionNotAllowed, User provided encryption keys are not allowed in this operation.
The object was stored using a form of Server Side Encryption. The correct parameters must be provided to retrieve the object.
EntityTooLarge, Your proposed upload is larger than the maximum allowed size.
EntityTooSmall, Your proposed upload is smaller than the minimum allowed size.
IllegalComplianceRequest
IllegalVersioningConfigurationException, The versioning configuration specified in the request is not valid.
IncompleteBody, You did not provide the number of bytes specified by the Content-Length HTTP header.
InvalidACLRequest, You must provide only one of either ACL headers or an XML body when setting ACLs.
InvalidArgument
InvalidBucketName, The specified bucket is not valid.
InvalidEncryptionAlgorithmError, The Encryption request you specified is not valid. Supported value: AES256.
InvalidPartOrder, The list of parts was not in ascending order. Parts must be ordered by part number.
InvalidPart, One or more of the specified parts could not be found. The part may not have been uploaded, or the specified entity tag may not match the part's entity tag.
InvalidPolicyDocument, The content of the form does not meet the conditions specified in the policy document.
KeyTooLongError, Your key is too long.
LoggingBucketSameOwner, The logging target bucket must have the same owner as the bucket being logged.
MalformedXML, The XML you provided was not well formed or did not validate against our published schema.
MetadataTooLarge, Your metadata headers exceed the maximum allowed metadata size.
RequestTimeout, Your socket connection to the server was not read from or written to within the timeout period.
TooManyBuckets, You have attempted to create more buckets than allowed.
TooManyComponents, A composite object may not have more than 1024 components.
UnresolvableGrantByEmailAddress, The email address you provided does not match any account on record.
StorageQuotaExceeded, Your account has surpassed it's storage limit.
BucketAccountInactive, The account that owns this bucket is not active.
StatusGoneConnectionClosed, Network connection was closed.410
StatusUnprocessableEntityDataUnrecoverable, The data in the request is unrecoverable. Please contact customer support.422
StatusConflictDeleteConflict409
EntityAlreadyExists
EntityTemporarilyUnmodifiable, The entity is temporarily unmodifiable. Please try again later.
Limit Exceeded
OperationAborted, A conflicting conditional operation is currently in progress against this resource. Please try again.
BucketAlreadyExists
BucketNotEmpty
ComplianceSettingsLocked, The compliance settings are now locked and cannot be changed.
StatusNotFoundNoSuchEntity404
NoSuchLifecycleConfiguration, The lifecycle configuration does not exist.
NoSuchBucket, The specified bucket does not exist.
NoSuchBucketPolicy, The bucket policy does not exist.
NoSuchKey, The specified key does not exist.
NoSuchReplicationConfiguration, The replication configuration does not exist.
NoSuchTagSetError, There is no tag set associated with the bucket.
NoSuchUpload, The specified upload does not exist. The upload ID may be invalid, or the upload may have been aborted or completed.
NoSuchVersion, The specified version does not exist.
StatusNotImplementedNotImplemented, A header you provided implies functionality that is not implemented.501
StatusServiceUnavailableTemporarilyUnavailable, Resources for this operation are temporarily unavailable. Please try again later.503
StatusFoundKeyAlreadyExists302
StatusMethodNotAllowedMethodNotAllowed, This method is not allowed for other than the account owner.405
MethodNotAllowed, The specified method is not allowed against this resource.
StatusLengthRequiredMissingContentLength, You must provide the Content-Length HTTP header.411

TCP Error Codes

Wasabi also supports the following TCP error codes:

  • Unexpected EOF
  • Broken Pipe
  • Connection reset by Peer

“Always Consistent” Feature

Rather than providing “always consistent” operations, AWS S3 operations are “strong consistency.” When you perform an AWS S3 operation, the results that follow may not reflect the previous operation.

Wasabi provides an “always consistent” view of all operations. Any operation following another will have the same expected result. This eliminates the special programming needed to wait for completion of a prior operation. As an example, after a DELETE on an object, it is common to perform a HEAD operation to check that the deletion was successful. Wasabi will always return a successful HEAD after the DELETE operation.

Authenticating Requests

Wasabi supports autonomous and signature versions 2 and 4 compatible with AWS S3, for both headers and query parameters. Generally, the signature version 4 offers better security, but requires more compute time on both the client and server because of the overhead calculating the SHA256 hash. If performance time is critical to your application, use the version 2 signing and check the calculated MD5 (returned as the ETag header for an object) for data integrity.

For version 4 signing requests, the region used for Wasabi signing requests is always “us-east-1” which is the default AWS S3 region.

Wasabi does not support signature signing for browser based uploads and HTML form requests because this is used for web page operations. (Web page operations are not currently supported on Wasabi).

For signature version 2, Wasabi added subresource keys that are specified as query parameters on the request. The specific subresource keys are:

  • append
  • compose
  • force_delete=true

which are query parameters given for the PutObject and DeleteBucket operations. When using signature version 2, you need to include these in the calculation of the signing.

Not Supported in Wasabi

OperationDescription
SOAPAWS S3 has deprecated support for SOAP. As a result, Wasabi does not support any SOAP operations.