Errors

Partner API domain errors and string-based HTTP errors usually use:

{
  "error": "not_found",
  "message": "Product not found or access denied"
}

Some endpoints return a structured detail object, and FastAPI request-schema validation can return its standard detail array. Feed endpoints also publish a typed feed-error envelope with an action and status URL. Generate clients from the current environment OpenAPI and handle the documented error shape for the endpoint rather than assuming one universal body.

Common statuses

Status	Meaning	Client action
400	Domain rule or request rejected	Correct the request or business state; inspect error, message, or detail.
401	Missing, expired, or invalid credential	Refresh the marketplace session and exchange again where appropriate.
402	Account entitlement or count limit denied	Do not retry. Read the feature/limit fields and coordinate account access; paid checkout is currently disabled.
403	Authenticated identity lacks permission	Do not switch seller IDs. Confirm the signed-in seller and required capability.
404	Resource absent or hidden by seller scoping	Treat as not found; do not use response differences to probe ownership.
409	Duplicate, replay, or state conflict	Read the current resource, reconcile idempotency, then decide whether a new operation is valid.
413	Feed/upload exceeds the runtime envelope	Read /products/feed-contract, split the file, and use a new stable key for each part.
422	Request or feed validation failed	Correct fields or rows using the returned validation details.
429	Request limit reached	Respect Retry-After when present and use bounded backoff.
500	Unexpected server failure	Retain the request ID; retry only when the operation is replay-safe.
502 / 503	Upstream or service unavailable	Use bounded retry only for idempotent reads or replay-safe writes.

Domain error codes

Common machine-readable codes include:

• validation_error
• business_rule_violation
• invalid_state
• expired
• insufficient_balance
• not_found
• access_denied
• conflict
• internal_error

Codes and fields outside this list can exist for a specific module. Branch on the current response contract, not the human-readable message.

Correlation and safe retry

Responses passing through the Partner API request-context middleware include X-Request-ID. Retain it with:

• method and path;
• timestamp;
• seller-safe resource IDs;
• idempotency key, if used;
• response status and body; and
• the current state observed before retry.

Never blindly retry a write after a timeout or 5xx. First read the resource or idempotency record to determine whether the operation committed. Feed runs and other replay-safe workflows document their own keys and status endpoints.

Examples

Domain/HTTP error:

{
  "error": "invalid_state",
  "message": "Cannot accept order in status 'shipped'"
}

FastAPI request validation can instead resemble:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "business_name"],
      "msg": "Field required"
    }
  ]
}

Use Authentication for credential failures and Seller Integration Program for feed and replay handling.