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

In September 2026, Amazon Shipping will introduce descriptive, text-based error codes in the code field and unique message values across GetRatesV2 and OneClickShipment APIs worldwide.

Summary

Phase 2 builds on the Phase 1 enhancement (May 2026) which standardised the details field. Phase 2 now enhances the code and message fields:

What is Changing?

Phase 1 enhanced the details field with actionable messages and numeric identifiers (EECs). The code field remained generic (InvalidInput for all 4xx, InternalFailure for 5xx).

Phase 2 introduces:

1. Descriptive code values — The code field now contains a self-describing UPPER_SNAKE_CASE identifier (e.g., INVALID_SHIP_DATE_IN_PAST, NO_PICKUP_SLOTS_AVAILABLE). Developers can programmatically match on specific error scenarios without parsing the details string.

2. Unique message per error — Each error returns a concise, factual description in the message field. This replaces the generic "Invalid input." text.

3. details field unchanged — The actionable guidance and EEC suffix introduced in Phase 1 remain exactly as-is. No changes to details.

4. New error codes added — 24 Dangerous Goods (DG) validation codes, 7 New service codes, and additional coverage scenarios.

Response Structure — Phase 2 (errors[x])

{
  "errors": [{
    "code": "INVALID_SHIP_DATE_IN_PAST",
    "message": "Ship date is in the past.",
    "details": "Ship date is in the past. Please select a future date. (D-505)"
  }]
}

Response Structure — Phase 2 (GetRatesV2 Ineligibility)

{
  "payload": {
    "rates": [...],
    "ineligibleRates": [{
      "serviceId": "SWA-UK-PRIME-PREM",
      "serviceName": "Amazon Shipping One Day",
      "carrierId": "AMZN_UK",
      "carrierName": "Amazon Shipping",
      "ineligibilityReasons": [{
        "code": "NO_PICKUP_SLOTS_AVAILABLE",
        "message": "No pickup slots available for the selected date. Please adjust pickup time or select a different date. (S-503)"
      }]
    }]
  }
}

Note: For GetRatesV2 ineligibility reasons (HTTP 200), the schema remains two fields (code + message).
Only the code value changes from generic enum values (e.g., NoSlotsFound) to descriptive UPPER_SNAKE_CASE (e.g., NO_PICKUP_SLOTS_AVAILABLE).
The message field continues to carry actionable guidance + EEC suffix as delivered in Phase 1.

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:

• Match on the code field value for programmatic error routing (e.g., if code == "InvalidInput")
• Display or log the message or details fields to end users or internal systems
• Parse ineligibleRates[x].ineligibilityReasons[x].code for rate-shopping logic

What Action is Required?

Required (if matching on code):

• If your integration matches on code == "InvalidInput" or code == "InternalFailure", you must update your logic before the deprecation period ends. Options:
  • Match on specific new codes (e.g., INVALID_SHIP_DATE_IN_PAST)
  • Implement a fallback/wildcard pattern that handles unknown code values gracefully

Recommended:

• Use the new descriptive code values for programmatic error routing and alerting
• Update any logging or dashboards that reference the code field
• Review the complete error code tables below for the full set of new values

Not Required:

• No changes to details field parsing — it remains identical to Phase 1
• No changes to authentication, endpoint URLs, or request payloads
• The three-field response schema (code, message, details) remains the same

Fallback Template

• When our error code mapping layer recognizes the error scenario → the response returns the descriptive Phase 2 code and message
• When the error is not mapped in our layer (e.g., an edge case or new error) → the fallback template still applies, and the response will contain the generic fallback values

Recommendation: Design your error handling to recognize specific Phase 2 codes, but always include a default/else branch for unrecognized code values. This ensures resilience against both unmapped errors and future code additions.

Error Code Reference — GetRatesV2 API

Endpoint: POST /shipping/v2/shipments/rates

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.

400 — Input Errors

403 — Authentication Errors

500 — Server-Side Errors

Error Code Reference — OneClickShipment API

Endpoint: POST /shipping/v2/oneClickShipment

Response Structure — Phase 2

{
  "errors": [{
    "code": "CREDIT_LIMIT_ENFORCED",
    "message": "Insufficient credit balance on the account.",
    "details": "Insufficient credit balance. Please add funds to your account or contact your account manager or support. (A-303)"
  }]
}

400 — Input Errors

403 — Authentication Errors

422 — Valid Syntax, Unprocessable

500 — Server-Side Errors

New Error Codes — Dangerous Goods (DG) Validation

The following 24 error codes are new additions in Phase 2, providing granular validation for Dangerous Goods shipment attributes. These apply to both GetRatesV2 and OneClickShipment.

DG — Missing Required Fields (HTTP 400)

DG — Impermissible Values (HTTP 400)

DG — Invalid Combinations (HTTP 422)

Transition Period

• 60-days pre-announcement before activation backwards compatibility
• During transition, the fallback template may still return generic error values for any unmapped scenarios
• After full rollout, all mapped error scenarios will return Phase 2 descriptive codes

Multi-Error Response Behavior

The multi-error behavior documented in Phase 1 remains unchanged. When a single request triggers multiple errors:

The errors array contains all applicable error codes with their new descriptive Phase 2 code values. The HTTP status of the response reflects the highest-priority error.

FAQs

1. Is this a breaking change?
The schema structure (code, message, details) remains unchanged. However, the values in code and message change. If your integration matches on code == "InvalidInput", you must update your logic. If you only parse details for identifiers, no change is needed.

2. Will InvalidInput and InternalFailure stop appearing entirely?
Not immediately. This will still surface as a fallback for any error scenario not yet mapped in our Phase 2 layer. Over time, coverage will expand and generic values will become increasingly rare.

3. Can I still rely on the details field and EEC identifiers from Phase 1?
Yes. The details field is completely unchanged. All EEC identifiers (D-701, A-303, S-503, etc.) remain in the details field exactly as delivered in Phase 1.

4. What's the relationship between the code field and the EEC in details?
They represent the same error scenario. The code field is a human-readable UPPER_SNAKE_CASE identifier for programmatic matching. The EEC (e.g., D-701) in the details field is a compact numeric identifier for support triage and dashboards. Both are unique per error condition.

5. Will the EEC identifiers (e.g., D-701, A-303) in the details field remain long-term?

The EEC identifiers will continue to be present in the details field for the foreseeable future. As the descriptive code field matures and becomes the primary identifier for programmatic use, we anticipate simplifying the details field in a future release to focus solely on actionable guidance — without the numeric suffix. Any such change will be pre-announced with sufficient lead time. For now, both remain available and stable.

6. Are the same code values used across both GetRatesV2 and OneClickShipment?
Yes. When the same error scenario occurs in both APIs, the code value is identical (e.g., NO_PICKUP_SLOTS_AVAILABLE appears in both GetRatesV2 ineligibility and OneClick 422). The difference is the HTTP status and response path.

7. How should I handle unrecognised code values?
Always include a default/fallback branch in your error-handling logic. New codes may be added over time, and the fallback template may still return generic values for unmapped scenarios.

8. Does this affect GetRatesV2 ineligibility message values?
For GetRatesV2 ineligibility reasons (HTTP 200), the message field remains unchanged — it continues to carry actionable guidance + EEC suffix as delivered in Phase 1. Only the code value changes.

9. Does this affect the details field for 4xx/5xx errors?
No. The details field remains exactly as delivered in Phase 1 across all HTTP error responses.

10. Will PurchaseShipment also receive Phase 2 codes?
Yes. PurchaseShipment shares the same response template as OneClickShipment. The D-705 (INVALID_OR_EXPIRED_RATE_ID) code already documented in Phase 1 will also receive the Phase 2 descriptive code treatment.

11. What about the new DG error codes (D-600 to D-623)?
These are net-new codes introduced alongside Phase 2. They apply to shippers onboarded for Dangerous Goods who submit invalid hazmat attributes. They were not present in Phase 1.

12. I'm a 3P integrator — do I need to update my platform?
Yes. If your platform matches on code values for error routing, you must update to recognise the new descriptive codes. If you only log or display the details field, no change is needed.