Error Handling

Amazon External FulFillment raises errors as API responses for a variety of reasons. As a developer, you should be able to handle them and recover from them. This section documents the error responses from Amazon External FulFillment and gives you guidelines on how you could handle them.

Response Format

Amazon External FulFillment APIs return a standard error response in JSON format when any API invocation encounters an error or exception. This response will be returned every time the HTTP status code from the API response is 400 or greater. The fields in the error response are described below.

Field	Description
code	An error code that identifies the type of error that occurred.
message	A message that describes the error condition.

Sample Error Responses

Below are a few sample error response in JSON format.

500 Status Code

{
    "code": "InternalFailure",
    "message": "Internal failure occurred, contact Amazon support",
}

400 Status Code

{
    "code": "InvalidInput",
    "message": "Invalid input '123' for parameter 'locationId'",
}

HTTP Status Codes

Being a RESTful API, Amazon External FulFillment leverages the HTTP status code in the HTTP response to an API request to indicate the broad class of error that the system encountered. Below is a description of the possible HTTP status codes that Amazon External FulFillment APIs return.

Status Code	Status Message	Description
200	OK	API invocation was successful.
207	Multi-Status	API Request was partially successful
204	No Content	API invocation was successful and there is no response.
400	Bad Request	API invocation failed. The failure could be due to a variety of reasons such as invalid input, invalid workflow state, etc.
401	Unauthorized	API invocation failed as your connector is not authorized to make that API call. This could happen if either you AWS IAM signature is invalid or the authorization token present in the request is invalid.
403	Forbidden	API invocation is forbidden for the given parameters.
404	Not Found	The entity that the API is trying to load does not exist.
409	Conflict	This status code is returned if the API fails due to an idempotency check. For example, two inventory updates for the same SKU in the same location using the same inventory sequence number.
422	Unprocessable Entity	This is a specific status code returned when an order workflow API is invoked on an order which has been cancelled by the marketplace.
500	Internal Server Error	An internal error occurred in the Amazon External FulFillment system. Reach out to Amazon Support for further assistance.
503	Service Unavailable	Amazon External FulFillment services are temporarily unavailable. Retry the API request.

Amazon External FulFillment Error Codes

While the HTTP status code response provides a broad indication of the class of error that occurred, Amazon External FulFillment error codes will provide a more fine-grained insight into the error. These error codes are described below.

Note

You should never rely solely on the HTTP status code of an API response to determine the type of error that occurred. It is possible that more than one class of errors share the same HTTP status code. Use the HTTP status code only to determine if the API call succeeded or not. For all non-2XX HTTP status response, you should check the Amazon External FulFillment error code returned in the response payload to determine the exact cause of the error.

Code	HTTP Status Code	Description
InternalFailure	500	An internal error occurred in the Amazon External FulFillment product. This is a permanent failure and will not succeed on retry contact Amazon Support for resolution.
ServiceUnavailable	503	A temporary failure occurred in the Amazon External FulFillment product. This is a temporary failure and will work on retry. Connector systems can choose to configure a retry strategy for this error code.
InvalidInput	400	One or more input parameters are invalid. This is a bad request and will not succeed on retry. Refer to Amazon External FulFillment API documentation for further details.
NotFound	404	Requested resource not found in the Amazon External FulFillment product. This is a bad request and will not succeed on retry. Check whether provided resource id is valid.
DuplicateRequest	409	Duplicate request found and operation can’t be performed. Requested operation is either already performed or still in progress. This is a bad request and will not succeed on retry. Connectors can choose to ignore this error code.
Forbidden	403	Operation is forbidden for the parameters provided in the API request. This operation will not succeed on a retry.
ServerBusy	409	Requested operation will be ignored because the Amazon External FulFillment product is already working on another process for the same order. This is a retryable failure and might work on retry. This error code implies that connector is trying to use the order workflow in an non-standard way. Refer to the Amazon External FulFillment API documentation for further details.
OperationNotPermitted	400	Requested operation is invalid and can’t be performed because the Amazopn External FulFillment product does not support requested operation in the current workflow state of the order. This is a bad request and will not succeed on retry. This error code implies that connector is trying to use order workflow in a non-standard way. Refer to the Amazon External FulFillment API documentation for further details.
StateConflict	409	Requested inventory quantity cannot be updated because the inventory sequence number provided is out-of-sequence. This is a bad request and will not succeed on retry. Refer to the Amazon External FulFillment API documentation for the correct usage of the inventory sequence number.
OrderCancelled	422	Requested operation cannot be processed because the order has been cancelled by the marketplace. This operation will not succeed on retry. This error code can be used to identify that order has been cancelled and no further operations need to be performed on the order.