Troubleshoot error codes

Use this page to identify and resolve Walmart Marketplace API errors. It covers standard error codes, typical causes, and clear fixes. It also documents rate limit behavior and common scenarios.

Error response format

Most APIs return a JSON error object with a code, message, category, severity, and sometimes the field that failed validation.

{ "errors": [ { "code": "INVALID_REQUEST_PARAM", "message": "The value provided for 'sku' is invalid.", "category": "DATA", "severity": "ERROR", "field": "sku" } ]
}

Note: If the gateway is unreachable, the response may include only an HTTP status such as 503 Service Unavailable.

Note: Include a unique correlation ID on every request to aid traceability. Use the WM_QOS.CORRELATION_ID header with a UUID.

Standard error codes

The table summarizes common errors across Marketplace APIs. The “What to do” column gives a practical next step.

Error code	HTTP	Meaning	Typical cause	What to do
`SOME_CONTENT_NOT_FOUND`	206	Partial content	Not all requested data was available	Handle partial results and request missing items if needed.
`INVALID_REQUEST`	400	Bad request	Body shape does not match schema	Validate JSON or feed before sending.
`INVALID_REQUEST_HEADER`	400	Bad request	Missing or malformed header, including correlation ID	Add required headers and use a valid `WM_QOS.CORRELATION_ID`.
`INVALID_REQUEST_PARAM`	400	Bad request	Invalid query or path parameter	Check parameter names, types, and allowed values.
`INVALID_REQUEST_CONTENT`	400	Bad request	Invalid body content	Verify request schema and field constraints.
`MISSING_REQUEST_HEADER`	400	Bad request	Required header missing	Add required headers such as `WM_SEC.ACCESS_TOKEN` after OAuth.
`MISSING_REQUEST_PARAM`	400	Bad request	Required parameter missing	Provide required parameters in path or query.
`MALFORMED_REQUEST_CONTENT`	400	Bad request	JSON or XML not parseable	Fix formatting issues and resend.
`UNAUTHORIZED`	401	Unauthorized	Missing or expired OAuth token, or wrong scopes	Obtain an access token, send it in `WM_SEC.ACCESS_TOKEN`, and ensure scopes allow the call.
`FORBIDDEN.GMP_GATEWAY_API`	403	Forbidden	Caller lacks permission to access the resource	Confirm the calling app has the right scopes and partner permissions.
`CONTENT_NOT_FOUND`	404	Not found	Resource does not exist	Verify identifiers and ingestion state before updating.
`URI_NOT_FOUND`	404	Not found	Wrong path or route	Verify base URL, path, and version.
`METHOD_NOT_ALLOWED`	405	Method not allowed	Using the wrong HTTP verb on the route	Use the supported method for the endpoint.
`INVALID_ACCEPT_TYPE`	406	Not acceptable	Unsupported `Accept` header	Send `Accept: application/json` unless documentation specifies another type.
`UNSUPPORTED_MEDIA_TYPE`	415	Unsupported media type	Wrong `Content-Type`	Use the content type expected by the endpoint or feed.
`RESOURCE_IS_LOCKED.GMP_RECEIVER_API`	423	Resource locked	Backend processing volume or record lock	Retry after a short delay. If it persists, wait up to 1 hour, then retry.
`REQUEST_THRESHOLD_VIOLATED`	429	Too many requests	Rate limit exceeded	Back off and respect rate limit headers. Refer to Rate limiting.
`INVALID_SYSTEM_STATE`	500	Server error	Inconsistent backend state	Retry with jitter. If repeated, open a support ticket with examples.
`SYSTEM_ERROR`	500	Server error	Internal issue or payload vs content-type mismatch	Confirm `Content-Type` and payload format, then retry with jitter.
`DOWNSTREAM_SYSTEM_TIME_OUT`	504	Gateway timeout	Dependent service did not respond	Retry with exponential backoff.

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:

On 429, pause requests for that API and read the headers.
Sleep until x-next-replenish-time, then resume at a lower rate.
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.

Error	What it means	How to fix
`ERR_PDI_0001` Malformed data	The entire feed file failed to parse due to malformed characters or structure.	Download the latest XSD, clean the file of special characters, revalidate, and resubmit.
`ERR_PDI_0034` Invalid data	Required fields missing or invalid values (for example, billable weight 0).	Validate against the latest XSD. Provide all mandatory fields with correct types and ranges.
`ERR_EXT_DATA_0101116` Title or price mismatch	Title or price is significantly different from existing listings for the same product ID.	Confirm the correct product ID, title, and price. Align with the catalog or contact Support to review the existing listing if the data is correct.

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.