Error codes

If an API call cannot reach the Walmart gateway, a basic HTTP error code (such as 503 Service Unavailable) is returned. However, a complete error response object is returned if the gateway is reached.

The following table shows the currently supported error code responses.

1. The first parameter provides the error description.
2. The second parameter shows the HTTP status code.
3. The third parameter specifies the error category.
4. The fourth parameter specifies the error severity.
5. The fifth parameter specifies whether the error response includes a field tag.

For example, the last error object on the right contains an INVALID_REQUEST_HEADER error encountered when invoking the GMP_ORDER_API. The error is a DATA ERROR in the WM_QOS. The CORRELATION_ID field (a request header) is null or blank.

Authentication failures

Walmart Marketplace uses OAuth 2.0. Remove legacy signature headers and send a valid access token on each call.

• Remove: WM_SEC.TIMESTAMP, WM_SEC.AUTH_SIGNATURE, WM_CONSUMER.ID
• Add: WM_SEC.ACCESS_TOKEN: <access token>

Common 401 causes and fixes:

• Token missing or expired. Refresh and resend.
• Insufficient scopes. Grant the app the required permissions and retry.
• Token present but placed in the wrong header. Use WM_SEC.ACCESS_TOKEN exactly.

Rate limiting and file size limits

When limits are exceeded, APIs respond with 429 Too Many Requests. Some feeds enforce file size limits and respond with 413 Payload Too Large.

Rate limit headers:

• x-current-token-count shows current tokens for the specific API.
• x-next-replenish-time shows when more tokens will be added.

Client behavior:

1. On 429, pause requests for that API and read the headers.
2. Sleep until x-next-replenish-time, then resume at a lower rate.
3. Use a token bucket in the client to stay within limits.

Troubleshooting by scenario

Orders

• Refund returns 400 Invalid request
  Cause The new refund would exceed the order total or earlier partial refunds.
  Fix Retrieve the order, sum prior refunds, ensure the new amount is within the remaining allowable amount, then resend.

• Cancel returns 400 Invalid request
  Cause Order already shipped or already canceled.
  Fix Retrieve the order, check status, and cancel only orders that are not shipped or canceled.

• Ship returns 400 Invalid request
  Cause Shipment notification sent for an order that is already shipped or canceled. Orders may auto-cancel if not shipped within 30 days.
  Fix Verify order status and ship only eligible orders created in the last 30 days.

Items, price, and inventory

• Update returns 400 Invalid request
  Cause Required parameter missing in URL, header, body, or wrong content type.
  Fix Check the endpoint’s required headers and fields. Send the expected Content-Type and a valid payload.

• Update returns 404 Not found
  Cause Updating an item that is not yet ingested or failed ingestion.
  Fix Check item ingestion status. If missing, ingest again, then retry the update.

• 405 Method not allowed
  Cause Wrong HTTP method for the route.
  Fix Use the documented method for the endpoint.

• 423 Resource is locked
  Cause Temporary lock during high-volume processing.
  Fix Retry later. If it recurs for an hour, reduce concurrency and retry.

Platform availability

• 500 Internal server error
  Cause Mismatch between Content-Type and payload format, or a transient internal issue.
  Fix Verify headers and payload. Retry with exponential backoff and jitter.

• 503 Service unavailable
  Cause Gateway unavailable.
  Fix Wait briefly and retry. If the outage persists, contact Support with examples.

Feed validation and item-level data errors

These indicate data that failed validation at file or item level.

Note: Treat “XML” as the feed file content or the request body, depending on the API.

Note: Re-download the latest schemas before resubmitting large corrections.

The Feed Item Status API allows you to track the status of the FITMENT_ACES and FITMENT_PIES feed uploads.

These are the feed statuses:

• ERROR: File is either REJECTED due to File validation failed or file has FAILED due to File not processed, or due to some issues while unzipping, format of error, etc.
• INPROGRESS: File APPROVED as File is accepted; File is ACCEPTED as File accepted for processing of individual records; PROCESSING: File processing in progress.
• PROCESSED: File has been processed successfully without any issues; File processed, however few records in the file had some issues which are marked as errors and can be downloaded using ERROR DOWNLOAD API

Note: If a request returns a Feed status of PROCESSING, you should continue calling until a different status is retrieved. The recommended calling intervals for Item is 15 minutes, 1 hour, 2 hours, and every 4 hours. To learn more about ingestion status, visit Feed status API for tracking fitment files.

Related topics

• OAuth 2.0 authorization
• OAuth authentication (header changes)
• Rate limiting
• Handle report errors
• Troubleshooting common integration errors (Marketplace Learn)