Marketplace API Errors

The canonical /api/marketplace/* serializer emits errors using Content-Type: application/problem+json and the RFC 9457 Problem Details shape.

code, type, title, and status come from the versioned canonical registry. detail is safe localized guidance. When a route has a stable application reason, reasonCode carries it without changing the HTTP category in code. Provider messages and evidence references are deliberately not part of the public response. Log requestId when present; never use it as an idempotency key.

A client must consume the response body exactly once. When the media type is application/problem+json, validate Problem Details instead of looking for legacy {success,error,code} fields; use detail for user guidance, reasonCode (falling back to code) for workflow branching, and the actual response status for HTTP branching. Do not attempt a second JSON read for malformed Problem Details; fail closed as an unverified response.

revision_conflict means the aggregate changed after your read. Fetch the current resource, rebuild the command from that revision, and submit it with a new idempotency key.

too_early (HTTP 425) means the same idempotent command is still in progress. Honor Retry-After, then poll the command receipt or retry with the same idempotency key; do not create a replacement key while the original outcome is unresolved.

For rate_limited, wait for Retry-After and add jitter. Retry unavailable only for idempotent operations. For internal_error on a write, first reconcile the resource or command receipt because the outcome may be unknown.

See the versioned contract for the complete code registry and compatibility rules.

The OpenAPI 3.1 registry contract describes the public problem-type lookup endpoint and links the canonical JSON Schema. Its declared scope is the problem registry only; it is not a claim that every Marketplace business-route request and success payload has been published as OpenAPI.

The canonical JSON Schema and AsyncAPI 3.1 event contract are published from byte-identical generated mirrors. A missing or drifting public artifact fails the Marketplace PR gate.

Routes using the canonical Marketplace serializer share one response seam. An HTTP error or a legacy success: false/ok: false result is converted to Problem Details; a failure that accidentally omits its error status is failed closed as internal_error with HTTP 500.

This registry is distinct from Partner v1 PARTNER_* problem codes and PDF partner success:false/code JSON errors. Select parsing by Content-Type and the route contract rather than applying this registry to every API. Honor Retry-After when present; Partner credential quota supplies resetAt in the body.