HTTP status codes

Use the HTTP status code as the primary indicator of the overall request outcome.

Status	Use when	Response body	Developer Action	Errors populated
200 OK	The request succeeded. Includes successful reads, list/search results, empty list results, idempotent no-op actions, and valid partial/truncated resource responses.	Yes	Handle as success. For empty lists, check `totalResults: 0` and an empty result array.	N/A
201 Created	A create operation completed successfully and created a resource.	Yes	Handle as success. Update clients to accept 201 (in addition to 200) for create calls. Read the created resource or returned ID.	N/A
202 Accepted	An async operation was accepted but is not complete.	Yes	Handle as success. Poll the status endpoint or job ID provided in the response.	N/A
204 No Content	The request succeeded but there is no response content. Also used for successful deletes.	No	Handle as success. Do not parse a response body. For delete operations: do not attempt to parse a response body. For info/status endpoints: treat 204 as “not found / not ready” rather than an error.	N/A
206 Partial Content	The server has successfully fulfilled a client request to retrieve only a specific portion of a file or resource, rather than the entire document.	Yes	Handle as success. Process the metrics returned in the response and inspect any omitted or unavailable metrics before deciding whether to retry or update campaign setup.	N/A
207 Multi-Status	A bulk operation had mixed outcomes: at least one item succeeded and at least one item failed.	Yes	Inspect item-level status and error details. Retry only failed items when appropriate. Do not treat 207 as a global failure.	Yes, per failed item
400 Bad Request	The request is syntactically invalid or failed field-level validation.	Yes	Fix the payload using details/errors and retry.	Yes
401 Unauthorized	The access token is missing, invalid, or expired.	Yes	Refresh or re-obtain the token and retry.	Yes
403 Forbidden	The token is valid, but the caller lacks required permission or scope.	Yes	Do not retry with the same credentials. Verify your access to the advertiser or resource. Contact your Walmart Connect account team if access is needed.	Yes
404 Not Found	A resource identified in the URL path does not exist or is not accessible.	Yes	Verify the resource ID/path. Do not retry. If the resource should exist, re-check creation or use list/metadata to confirm.	Yes
409 Conflict	The request conflicts with current resource state, readiness, or uniqueness constraints.	Yes	Read the error code in the response body. Check the current state or duplicate condition before retrying. For a state conflict, check the entity’s status before retrying. If not ready, poll until the resource is in `BUILT`, `ACTIVE`, or `AVAILABLE` state.	Yes
410 Gone	A previously valid resource is permanently expired or removed.	Yes	Request or create a new resource. Do not retry the expired reference.	Yes
429 Too Many Requests	The caller exceeded API rate limits or quota.	Yes	Wait for the `Retry-After` duration and apply exponential backoff.	Yes
500 Internal Server Error	An unexpected server or downstream error occurred.	Yes	Do not retry if the issue persists. Escalate and contact your Walmart Connect support team.	Yes

Error Handling

When an API returns an error, first use the HTTP status code to determine the type of failure. Then inspect the response body for additional information about what failed.

Error responses can include the following fields:

Field	Description
`code`	Indicates the outcome of the request or item, such as `success` or `failure`.
`details`	Machine-readable result or error codes. Use these codes for programmatic error handling.
`message`	Optional high-level, human-readable summary of the error.
`errors`	Structured diagnostics for a failed item. When present, use `errorType` for the error condition, `field` for the affected request field when applicable, and `description` for an explanation of the error and, when available, guidance on how to resolve it.

Example error response

{ "code": "failure", "details": ["ERROR_CODE"], "message": "One or more errors occurred.", "errors": [ { "field": "fieldName", "errorType": "ERROR_CODE", "description": "Explanation of the error and, when available, how to resolve it." }
]
}

Exact fields can vary by endpoint and error condition. See the endpoint's API Reference for the complete response schema.

Bulk and partial responses

Some APIs process multiple items in a single request. When a bulk request returns mixed outcomes, evaluate each item in the response independently. Successful items contain the fields defined for that endpoint's successful response, while failed items include error information describing the individual failure.

Do not treat a mixed-outcome response as a failure of every item. Process successful items normally and use the error information returned for failed items to determine the appropriate next action.

Response schemas vary by endpoint. See the endpoint Guide for workflow-specific response behavior and examples, and the API Reference for the exact response fields and schema.

Retry guidance

Response	General guidance
`400`, `403`, `404`, `410`	Do not retry unchanged. Correct the request, access, or resource reference first.
`409`	Retry only after the conflicting state or condition changes.
`429`	Wait for the `Retry-After` duration before retrying.
`5xx`, including `503`	Retry with backoff when the operation is safe to retry. Honor `Retry-After` when provided.
`520`, `521`	Treat as transient infrastructure failures and retry with backoff when the operation is safe to retry.

API Reference

This guide describes common behavior across Display APIs. For an endpoint's exact supported HTTP responses, response schema, field types, optionality, and examples, see that endpoint in API Reference.