Skip to main content

Error Specifications

Response Body​

In case of error, all Prime APIs error response structure is same. The error message body is as follows:

{
    "error": {
        "code": "Code",
        "message": "Message"
    }
}

The details of the fields present in the error message body is as follows:

  1. error.code: It contains a specific code that provides the reason for the error. This is a static value that doesn’t change for a specific error. Clients can use this value to record a metric and create an alarm on top of that metric. It can used for programmatic purpose. Example = BadRequest
  2. error.message: It contains more details about the error that can’t be included in the code. For example, for ‘BadRequest’, it can contain details pointing the reason for the request to be marked as bad request. No programmatic logic should be based on this field. However, it is safe for clients to use this field in their logging. It will not contain sensitive customer data.

HTTP Status Code​

In addition to error message body, the API will also return a standard HTTP status code. The below table list all the error scenarios, the HTTP status code and the error.code returned for those error scenarios. The table also provide the column ‘Retry’ which indicates whether the request should be retried or not.

HTTP status codeReason codeRetryDescription
400BadRequestNoIndicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request).
403MissingAuthenticationTokenNoAuthorization header is not provided.
403InvalidSignatureNo1. Signature is valid but expired. 2. Authorization header has some fields missing. 3. Authorization header fields are not constructed properly. 4. Date value present in the Authorization header is not valid. 5. Signature value present in the Authorization header doesn't match the calculated signature of the request.
403InvalidAuthenticationNoError in client authentication.
403AccessDeniedNo1. Client is trying to access the resource which they don't have permission to. 2. Client is passing the value of parameters/headers in the resource which they are not entitled to. For example, client is only allowed to pass 'US' in x-amzn-marketplace header but it passes 'GB'.
403InvalidCustomerIdentifierNoIndicates that customer details passed by the client are not valid and Prime is unable to recognise/authenticate the customer.
403MissingCustomerConsentNoIndicates that the customer is authenticated and identified by Prime sytems, but customer has not provided consent to the client for accessing the data attributes of the API resposne.
429RequestThrottledYes (with backoff)It can happen in two situations: 1. If client exceeds the allocated request quota for the resource. 2. If Prime service is under stress and decides to shed load by throttling requests.
500InternalServerErrorYes (with backoff)Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
503ServiceUnavailableYes (with backoff)Indicates that the server is not ready to handle the request.

Programming Guidelines​

  1. Only rely on this documentation: Outside of the response body and HTTP status code mentioned here, the client should not rely on any other aspect of the response for any logic at their end. For example, the response might include some headers. However, unless it is documented here, the client should not rely on those headers. This documentation is authoritative represent of response which will not change. Depending on the server technology, some new headers can be added and that’s why it is imperative that client should not rely on any undocumented specification.

  2. Future compatible change: The API can add more HTTP status codes in future. It is important that the logic is not written specifically to only expect these HTTP status codes. The client is requested to have the logic written in such a way that special handling (if needed) can be done in future phases not only for these status codes, but for any other 4XX and 5XX error codes as necessary.