Errors

GraphQL error shape

Errors from POST /graphql use the standard GraphQL envelope:

{
  "errors": [
    {
      "message": "..."
    }
  ]
}

When the request succeeds but the listing is absent, the response is 200 with data.listing: null — not an error:

{
  "data": {
    "listing": null
  }
}

Treat listing: null as unpublished or not found. Do not retry it.

Status	Meaning	Fix
`200`	Success	Check `data.listing` — it may be `null`
`400`	Invalid GraphQL request	Ensure the query uses `listing(slug: $slug)` as the root field
`403`	Embed key missing, invalid, revoked, or expired — or request origin not allowed	Supply a valid `X-Publix-Embed-Key` and ensure your origin is on the listing's allowlist
`422`	Missing query text or slug variable	Include `query` and `variables.slug` in the request body
`502`	Publix could not reach its upstream	Retry with exponential backoff and log the `X-Request-Id`

Every response includes an X-Request-Id header. Include this value when reporting issues.

400, 403, 422 — do not retry; fix the request first.
502 — retry with exponential backoff.
200 with listing: null — do not retry; the listing is unpublished, disabled, or does not exist.