Errors

Every JSON error carries a human-readable message — key off it. The one
exception is the 401, which is not JSON: the API key is validated at Sovrn's
gateway before the request reaches the service, and the body is a bare
text/plain string. Handle these cases:

Status	Meaning	Body
`400`	Validation failed	`{ "message": "<reason>" }` — e.g. `takeRate is a decimal fraction; expected 0 ≤ x ≤ 0.85`, `startDate must be today or later (UTC)`, `runOfNetwork and targeting are mutually exclusive; provide one or the other`, `unknown audience segment id(s): …`
`401`	API key missing, invalid, or malformed	`text/plain`, not JSON. One of three strings: `api key not provided` (no `x-api-key` header), `invalid api key` (unknown, revoked, or expired key), `invalid api key syntax` (malformed key)
`403`	Key valid but not permitted	`{ "message": "Partner not authorized for this API" }` or `{ "message": "Insufficient scope" }`
`404`	No deal request with that id on your account	`{ "message": "Deal request not found" }`
`502`	Sovrn could not reach the downstream deal system; nothing was persisted	`{ "message": "…", "upstream": "vulcan" }`

📘
Retrying
A 502 means nothing was persisted — it is safe to retry (use a unique deal
name). Treat unexpected 5xx responses other than 502 defensively: they
may not carry a JSON body. Do not JSON.parse a 401 — its body is a plain
string.

Validation is not uniform across targeting values

Worth knowing when debugging a deal that was accepted but isn't delivering:
audience.segmentids is the only targeting attribute whose values are
checked. An unrecognized segment id returns a 400 listing the ids in
question.

Every other attribute accepts any value of the right JSON type. A malformed
country code or ad-size token produces a deal that is created successfully and
then never matches traffic, with no error at any point. Use
GET /targeting-attributes/{attribute}/values
to check values before submitting, or see Targeting for the
exact format each attribute expects.