Errors
Every failure carries one structured object, and this page is its single definition: {error_code, error_message, stage, recoverable, details}. The same five-field envelope appears on synchronous error responses and on failed and rejected events; other pages reference this shape and none restates it. Switch on the code; messages are for humans.
| Code | Meaning |
|---|---|
INVALID_INPUT | Order failed validation (async path; synchronous problems return 422) |
PARSE_FAILED | Document workflow: the file could not be interpreted |
CURSOR_EXPIRED | 410: the after cursor on the event feed predates your retained stream. Sweep the order book, replay per order, then resume from a fresh feed read. |
STALE_RATE_CARD | Your rate version is behind; the rate_drift diff lists your_cost vs current_cost per line. Refresh and resubmit. |
INVENTORY_UNAVAILABLE | The requested periods lack availability (the only legitimate business rejection on price-valid orders). |
GRAIN_NOT_OFFERED | 422: a line named a grain it cannot book. details.product_id and details.grain name what was asked for, and details.grains lists what the seller sells. Two causes, one code: the product may never sell that grain, or the buyer's agreement may narrow it. details.permitted_grains is present only in the second case, so an agent can tell "never sold that way" from "not sold that way to you" without the response shape changing for anyone already handling it. The seller decides what it is willing to sell a month of, and a buyer cannot mint the grain by asking for it. |
GRAIN_CONFLICT | 409: catalog ingest rejected a product that offers the month grain while its card prices some month non-uniformly. A line locks exactly one rate across its whole period, so a month with two prices for one cell has no rate a month line could lock. The conflict report names the product and the month; nothing from the update is applied. |
DUPLICATE_EXTERNAL_REF | 422: an external_ref this seller already holds was reused. The refusal names what it collided with, because a non-unique external key is worse than no external key for the reconciliation it exists to serve. On a registry record it names the record that holds it (details.advertiser_id, details.campaign_id, or details.creative_id), and there the caller owns both sides of the collision so nothing leaks. On a relationship record it names the colliding record (details.agreement_id, details.buyer). On a catalog publish it names both products (details.product_ids) and refuses the whole request: uniqueness is a property of the resulting catalog rather than of any one entry, so the check runs on the catalog the update would produce, which is what catches two new entries sharing a ref as well as one colliding with a product the update carried forward. Nothing publishes and the taxonomy_version does not become current. |
UNKNOWN_ADVERTISER | 422: an advertiser_id that names no advertiser in the calling buyer's own registry, whether on an order's buyer_metadata, a campaign, or a creative. One answer for foreign and never-minted alike, deliberately: a refusal that distinguished the two would confirm that some other buyer holds the id. details.advertiser_id echoes what was sent, which the caller already knows. |
UNKNOWN_CAMPAIGN | 422: the same, for an order's buyer_metadata.campaign_id. |
UNKNOWN_CREATIVE | 422: the same, for a line's creative_id or an entry in its creative_splits. details.field names the line. |
REFERENCE_ARCHIVED | 422: a new reference to an archived registry record: an order create, a revision adding a line or a split, or a campaign or creative created under an archived advertiser. details names the object and the id. New only: an order that already cites the record keeps resolving it, and a revision carries forward what its predecessor referenced, which is what the snapshot rule exists to make safe. |
CREATIVE_LENGTH_MISMATCH | 422: a line whose spot_length differs from the stated length_seconds of the creative it references. details names the line, the creative, and both figures. Checked at the write that persists the reference, never client-side and never deferred to placed: an order holding committed inventory against a creative that cannot air in its slot is the state this refusal prevents. A creative that states no length is checked against nothing. |
DUPLICATE_DISCLOSURE_OVERRIDE | 422: a relationship's disclosure_overrides named one product_id twice. details.product_id names it. Refused rather than resolved by array order, because which entry wins would otherwise be an accident of how the seller happened to send them. "*" is a distinct key and never collides with a named entry. |
TENANT_MISMATCH | 403: the buyer_entity in your create body disagrees with the acting buyer your credential resolves to. The platform never books under the tenant it resolved when you asserted a different one, because that would surface as a billing dispute rather than an auth error. Send no buyer_entity and it is filled in for you. See acting-buyer identity. |
OUTSIDE_RATE_CARD | Requested combination is not on the applicable card |
SELLER_REJECTED | The seller's approver declined (reason persisted and surfaced) |
BUYER_REJECTED_INTENT | You rejected at confirmation; surfaces as canceled |
CREDIT_LIMIT | Cleared trades only: the order would breach a credit or exposure cap; fails fast at create, before anything books |
PLACEMENT_FAILED | The booking write into the seller's traffic system failed, so the order did not reach placed; ops is on it |
INTERNAL_ERROR | Our fault; the audit trail will say exactly where |
Per the price-clearance invariant, a rate mismatch on matching versions is a VAMOS defect, not your error. It pages us, not you.