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.

API Error Handling and Retries

Amazon External Fulfillment emphasizes client-side error handling for API interactions. Specifically, in the "Error Handling" section, it categorizes API errors and indicates which ones are retryable.

Retryable Errors: These are typically transient issues, such as network problems, server-side throttling, or temporary service unavailability. The client application should implement retry logic, potentially with exponential backoff, to handle these errors.

When calling the External Fulfillment API, the behavior of retries would typically be handled by the client application making the API call, rather than by the platform itself. Best practices for API retries often involve:

• Implementing a finite number of retries (<4 attempts).
• Using an exponential backoff strategy, which increases the waiting time between retries.
• Checking the response's HTTP status code and only retrying for temporary or intermittent errors (e.g., 500, 503, 429, 409 etc.).

Non-Retryable Errors: These include issues like invalid input parameters, authentication failures, or authorization problems. Retrying these errors without addressing the underlying cause will not resolve the issue. The client application should handle these by reporting the error or taking corrective action.

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.

API Error Codes & Remediation Steps

HTTP Code	SC Error Code	Error Short Code	Description	Remediation Steps
500	SC_00000	InternalFailure	Internal failure occurred, contact Amazon support	Contact Amazon support team with API logs and error details.
503	SC_00001	ServiceUnavailable	Temporary failure occurred, retry operation	Implement exponential backoff retry logic. Wait a few minutes and try again.
429	SC_00007	RateLimited	Temporary failure occurred, retry operation after some time	Reduce request frequency. Implement rate limiting on client side. Check API quotas.
400	SC_00002	InvalidInput	Invalid input '%s' for parameter '%s'	Check API documentation for correct parameter format and constraints. Validate input before sending.
400	SC_00002	InvalidInput	Invalid input, '%s': '%s' can't be higher than '%s'	Review business logic in request. Ensure comparative values are valid (e.g., min < max).
400	SC_00002	InvalidInput	At least one field is mandatory in the input payload	Include required fields in request payload. Check API documentation for mandatory fields.
404	SC_00003	NotFound	Requested Entity with '%s' '%s' is not found	Verify entity/shipment exists. Check if you have correct access permissions to retrieve shipment details for the seller.
404	SC_00003	NotFound	Requested artifact of type '%s' not found	Confirm document exists and you have correct access permissions. Check document type is correct.
409	SC_00004	DuplicateRequest	Duplicate clientToken exists for '%s' '%s'	Use unique clientToken/sequenceNumber. Check if request was already processed successfully.
409	SC_00004	DuplicateRequest	Requested operation is already in progress for '%s' '%s'	Wait for current operation to complete. Check operation status before retrying.
403	SC_00005	Forbidden	Request is forbidden	Check authentication credentials and SP-API roles permissions. Ensure API key has necessary access rights.
409	SC_10000	ServerBusy	Requested operation will be ignored as workflow is already processing other request(s)	Wait for current workflow to complete. Implement retry mechanism with appropriate delay.
400	SC_10001	OperationNotPermitted	Requested operation is not permitted in the current order state	Check current order status in getShipment API and allowed operations. Follow correct order processing workflow.
400	SC_20000	InvalidInput	Requested quantity '%s' is more than existing inventory quantity '%s'	Ensure the order is not cancelled. Validate lineItemId, corresponding quantity and correct accordingly.
409	SC_20002	StateConflict	%s is in conflict with existing client sequence number %s	Use increasing sequence numbers. Sync latest sequence number before retry.
412	SC_00006	StateConflict	Entity Version '%s' is in conflict with existing entity version '%s'	Fetch latest entity version before update using If-Match or If-Unmodified-Since headers. Update latest entity version or timestamp in rfc 2616 format.
422	SC_00006	OrderCancelled	Cannot process the request because the order is already cancelled	Check order status before processing. Handle cancelled orders appropriately in your workflow.
400	SC_30001	ShiplabelGenerationFailure	Cannot process the request because either package dimensions are incorrect or the carrier capacity has been completely utilized	Verify input package dimensions. Try with different package dimensions using updatePackage API or wait for the carrier capacity to be available.
400	SC_30002	TransCapacityBreachedFailure	The capacity for the site is breached	Try processing after the current EXSD or wait for the carrier capacity to be available.
400	SC_30003	IncorrectPackageDimensionsFailure	Package dimensions or weight is incorrect	Ensure the dimensions are within the channel/carrier limits. Verify and update accordingly.
400	SC_30004	InvalidInput	The given pickup-slot is no longer available and is expired	Select a new pickup slot. Implement real-time slot availability check.
400	SC_30005	StateConflict	Dispatch-after-date '%s' of the order is greater than the current time	Wait until dispatch-after-date before processing. Schedule processing for correct time.
409	SC_40000	DuplicateRequest	An event subscription already exists for the merchant	Check existing subscriptions before creating new ones. Update existing subscription if needed.
400	SC_30007	OperationNotPermitted	No invoice available for shipment '%s'	Wait for invoice availability. Check invoice status using getShipment(s) API. Applicable for BR marketplace.
400	SC_00005	InvalidInput	Maximum number of retry reached for order '%s' or on a operation of order, Please try after '3600' seconds.	Wait for 1 hour (3600 seconds) cooling period before attempting the operation again. Meanwhile, verify and correct any bad input to ensure successful processing on the next attempt.