Launch Announcement: Amazon Shipping Error Code Enhancement - Phase 1 (WW)

In May 2026, Amazon Shipping will introduce enhanced, standardised error codes and messages across GetRatesV2, PurchaseShipment and OneClickShipment APIs worldwide.

Summary

This launch delivers standardised error codes with actionable messages across the Amazon Shipping V2 API. Each error now includes a concise, actionable message appended with an identifier from defined families — A-xxx, D-xxx, S-xxx.

Key difference: GetRatesV2 also surfaces service-eligibility issues (no slots, promise miss, no coverage, etc.) as HTTP 200 responses with ineligible rates in the ineligibleRates array along with HTTP 400 statuses while OneClickShipment surfaces the same scenarios with HTTP 422 and HTTP 400 error responses.

What is changing?

The error identifiers are useful for debugging and support ticket correlation. A future release will introduce stable, descriptive codes in the code field for programmatic use.
The changes apply to both the GetRatesV2 and OneClickShipment APIs, but the response paths differ:

For OneClickShipment — every error in the errors[x].details field now includes:

• A unique error identifier (e.g., D-701, A-301, S-503)
• A concise, actionable message following the format: what went wrong + how to fix it + (identifier)
• Proper HTTP status codes: 400 (input error), 403 (auth failure), 422 (valid syntax but unprocessable), 500 (server-side)

For GetRatesV2 — in addition to the above error response format (400, 403, 500):

• Service-eligibility issues are returned as HTTP 200 in the ineligibleRates[x].ineligibilityReasons array
• Each ineligibility reason now includes the same standardised message and identifier in the message field
• The code field contains the ineligibilityReasonCode enum value (e.g., NoSlotsFound, MISSES_PROMISE)

Which marketplaces are affected?

This change applies to all marketplaces worldwide (US, UK, FR, IT, ES, IN).

Who is affected?

Developers who integrate with the Amazon Shipping V2 API (GetRatesV2 and OneClickShipment) are affected. This is particularly relevant for applications that:

• Parse the errors[x].details field for error handling logic
• Parse the ineligibleRates[x].ineligibilityReasons[x].message field (GetRatesV2)
• Reference error identifiers in the details field for troubleshooting (e.g., D-505, A-306)
• Display error messages to end users

What action is required?

Recommended:

• Review the updated error messages in the details field for improved troubleshooting context.
• The error identifiers are useful for debugging and support ticket correlation.
• If you previously referenced old identifiers (e.g., S-505, A-200), note the prefix corrections in the table below.
• A future release will introduce stable, descriptive codes in the code field for programmatic use.

Not Required Immediately:

• This update is backward compatible at the schema level. The errors array structure (code, message, details) remains unchanged. Only the content of the details field is enhanced.

Error Code Reference — GetRatesV2 API

The following error codes apply to the GetRatesV2 API (POST /shipping/v2/shipments/rates)

Important: In addition to standard HTTP error responses (400, 403, 500), the GetRatesV2 API also surfaces certain scenarios as HTTP 200 with ineligible rates. These are returned in the ineligibleRates[x].ineligibilityReasons array within a successful response, indicating why a specific service/rate is not available.

Response Structure — Error (400/403/500)

{
  "errors": [{
    "code": "InvalidInput",
    "message": "Invalid input.",
    "details": "Package dimensions exceed the allowable limits. Please refer to API documentation for allowable limits. (D-400)"
  }]
}

Response Structure — Ineligible Rate (200)

{
  "payload": {
    "rates": [...],
    "ineligibleRates": [{
      "serviceId": "SWA-UK-PRIME-PREM",
      "serviceName": "Amazon Shipping One Day",
      "carrierId": "AMZN_UK",
      "carrierName": "Amazon Shipping",
      "ineligibilityReasons": [{
        "code": "NoSlotsFound",
        "message": "No pickup slots available. Please adjust pickup time. (S-503)"
      }]
    }]
  }
}

Complete Error Code Table

200 — Ineligibility Reasons (Ineligible Rates)

These are returned within a successful HTTP 200 response as part of the ineligibleRates array. They indicate why a specific rate/service is not available but do not prevent the API call from succeeding.

400 — Shipper Input Errors

403 — Authentication Errors

500 — Server-Side Errors

Error Code Reference — PurchaseShipment API

The following error codes apply to the PurchaseShipment: API ( POST /shipping/v2/shipments)

The PurchaseShipment API shares the same response structure as OneClickShipment. Currently, one standardised error code applies specifically to this endpoint:

400 — Shipper Input Errors

Note: PurchaseShipment requires a valid rateId obtained from a prior GetRatesV2 call. If the rate has expired or is invalid, the API returns a 400 with identifier D-705.

Error Code Reference — OneClickShipment API

The following error codes apply to the OneClickShipment API (POST /shipping/v2/oneClickShipment).

Response Structure

{
  "errors": [{
    "code": "InvalidInput",
    "message": "Invalid input.",
    "details": "Package dimensions exceed the allowable limits. Please refer to API documentation for allowable limits. (D-400)"
  }]
}

Complete Error Code Table

400 — Shipper Input Errors

403 — Authentication Errors

422 — Valid Syntax, Unprocessable

500 — Server-Side Errors

Note: These identifiers are provided for reference and troubleshooting. Identifier prefixes and numbering may evolve in future phases as the error framework matures. A future release will introduce stable, descriptive text-based codes in the code field for programmatic use.

OneClickShipment — Multi-Error Response Behaviour

The OneClickShipment API evaluates multiple eligibility conditions simultaneously. When a single request triggers errors that would individually map to different HTTP status codes (400, 422, 500), only one HTTP status code can be returned per response. The following priority determines which status code is surfaced:

HTTP Status Priority (Highest → Lowest)

Multi-Error Scenarios

Response Structure — Multi-Error

When multiple errors are present, the errors array contains all applicable error codes regardless of their individual HTTP status category. The HTTP status of the response reflects the highest-priority error per the table above.

{
  "errors": [
    {
      "code": "InvalidInput",
      "message": "Invalid input.",
      "details": "Ship date is in the past. Please select a future date. (D-505)"
    },
    {
      "code": "InvalidInput",
      "message": "Invalid input.",
      "details": "No pickup slots available. Please adjust pickup time. (S-503)"
    },
    {
      "code": "InvalidInput",
      "message": "Invalid input.",
      "details": "Account is paused. Please wait for pause period to end or contact support to resume. (S-501)"
    }
  ]
}

In this example: D-505 is a 400-level error, S-503 and S-501 are 422-level errors. The response HTTP status is 400 (highest priority). The developer should fix the ship date first; on retry, the 422 issues will surface if still applicable.

Key Takeaway

Developers should fix errors in priority order: input errors (400) first, then account/config issues (422). Server errors (500) that persist after fixing client-side issues should be raised to support. This approach ensures coherent resolution — fix your side first, then escalate what requires Amazon-side action.

Note: This multi-error behaviour is analogous to GetRatesV2's ineligibleRates array, where multiple ineligibility reasons are returned in a single 200 response. For OneClick, instead of surfacing them as 200 ineligibility reasons, they are returned as errors within the errors array under a single prioritised HTTP status code.

Error Identifier Prefix Corrections

The following error scenarios have had their identifier prefix corrected to align with the error family classification:

HTTP Status Code Logic

Example: Before and After

Before (Generic):

{
  "errors": [{
    "code": "InvalidInput",
    "message": "Invalid input.",
    "details": "No offerings found for the given request. Either it is out of coverage or dimensions or weight are not supported"
  }]
}

After (Specific):

{
  "errors": [{
    "code": "InvalidInput",
    "message": "Invalid input.",
    "details": "No pickup slots available. Please adjust pickup time. (S-503)"
  }]
}

After (Specific — GetRatesV2 Ineligible Rate):

{
  "payload": {
    "rates": [...],
    "ineligibleRates": [{
      "serviceId": "SWA-UK-PRIME-PREM",
      "serviceName": "Amazon Shipping One Day",
      "carrierId": "AMZN_UK",
      "carrierName": "Amazon Shipping",
      "ineligibilityReasons": [{
        "code": "NoSlotsFound",
        "message": "No pickup slots available. Please adjust pickup time. (S-503)"
      }]
    }]
  }
}

FAQs

1. Will my existing integration break?
   No. The errors array structure (code, message, details) remains unchanged. The code and message fields retain their current values. Only the content of the details field (and ineligibilityReasons[x].message for GetRatesV2) is enhanced with standardised, actionable messages and error identifiers.

2. What is the difference between "Updated" and "New" error codes?

   • Updated: These error codes already exist in the API. Their messages have been rewritten to be more specific, actionable, and standardised. A unique error identifier has been added or corrected.
   • New: These error codes were not previously surfaced to API consumers. They were either returned as generic S-900 / InvalidInput or not exposed at all. They now have distinct, specific messages.

3. I match on specific strings in the details field. Will this break?
   Yes — if you perform exact string matching on the details field, your logic will need to be updated. The error identifiers appended to messages (e.g., D-701, S-503) are provided for reference and troubleshooting purposes. A future release will introduce stable, descriptive text-based codes in the code field, which will be the recommended field for programmatic error handling.

4. Are these error codes the same across GetRatesV2 and OneClickShipment?
   The error identifiers are the same for the same scenario. However, the response path differs: GetRatesV2 returns service-eligibility issues as HTTP 200 ineligible rates, while OneClickShipment returns them as HTTP 422 errors. Input validation errors (400) and auth errors (403) behave identically across both APIs.

5. What does the code field contain now?
   The code field (e.g., "InvalidInput", "Unauthorized") remains unchanged in this release. It continues to reflect the HTTP status category. The specific, actionable error information is in the details field. A future release will introduce descriptive text-based codes in the code field.

6. Will more error codes be added in future?
   Yes. This is Phase 1 of a multi-phase initiative. Future phases will expand coverage, improve downstream error propagation, and introduce enhanced logging.

7. How should I handle the 422 status code?
   A 422 response means your request syntax is valid but cannot be processed — typically due to account configuration, onboarding status, or service constraints. These are not retryable by simply resending the same request. Review the details message for the specific action required. Note: 422 applies to OneClickShipment only; GetRatesV2 does not return 422.

8. How do I parse ineligibility reasons in GetRatesV2?
   Check the ineligibleRates array in the response payload. Each entry contains an ineligibilityReasons array with a code (enum value) and message (standardised text with identifier). The identifiers are useful for troubleshooting.