Errors
All error responses use RFC 9457 Problem Details with Content-Type: application/problem+json.
Error structure
Use code for programmatic branching — title and detail may change, code does not.
Extension members
Some errors include additional structured fields beyond the standard six. These are RFC 9457 extension members — extra context that helps agents self-correct without parsing the detail text.
Extension members vary by error code. Use code to determine which extras are present.
Readiness-bridged errors
publish_failed includes the full readiness actions array — the same structured guidance you get from GET /v1/listings/{id}. Your agent gets the fix instructions inline with the error:
State and constraint errors
Other errors include flat metadata about the current state or constraint:
HTTP status codes
Common error codes
Handling errors in Python
Accessing extras in SDKs
Both SDKs expose extension members via error.extras — a dict/object of all fields beyond the standard six.
Unknown extension members are preserved verbatim — as the API adds new fields, your code receives them immediately without an SDK update.
Correlation IDs
Every response includes an x-correlation-id header. Include it when contacting support — it ties your request to the server-side logs.
Related
- Rate limits — handling 429 responses
- Idempotency — safe retries for POST requests
- Readiness — structured guidance that errors mirror