Error codes

Every refusal is an RFC 9457 problem document (application/problem+json) with a stable code. Branch on code, never on title or detail: a code, once published, is never renamed or reused; the titles are human text and may be reworded. The HTTP status is the one the code is answered with as a refusal. A few codes also appear as a reason inside a 200 body (the ad render and click confirmations answer {accepted: false, reason}).

Refusals are never billed. See Rate limits and errors for what to do with each class.

Retrieval requests

Code	Status	Meaning
sort_required	400	A sort is required
filter_required	400	A filter naming exactly one country is required
country_required	400	A country is required
unknown_field	400	Field not allowed for this collection
operator_not_allowed	400	Operator not allowed for this field
sort_not_allowed	400	Sort key not allowed for this collection
value_invalid	400	Value is not valid for this field
limit_exceeded	400	Limit exceeds the maximum
collection_unknown	400	Unknown collection
request_invalid	400	Request is not valid

Request signatures

Code	Status	Meaning
signature_missing	401	Request is not signed
signature_invalid	401	Request signature is not valid
signature_expired	401	Request signature is outside its validity window
key_unknown	401	Signing key is not registered or not live
nonce_reused	401	Nonce has already been used
digest_mismatch	400	Content-Digest does not match the body

Identity, roles and passkeys

Code	Status	Meaning
no_grant	403	You hold no grant on this party
permission_denied	403	Your roles on this party do not include this action
grant_expired	403	Your access to this party has expired
grant_deactivated	403	Your access to this party is deactivated
party_not_verified	403	The party must be verified for this action
party_suspended	403	The party is suspended
party_held	403	The party is on hold: its records stay live, new publishing is paused
party_not_funded	402	The party has no funds for this action
admin_hold	403	A new admin cannot change grants, keys or mandates for 24 hours
passkey_required	403	This action requires a passkey
device_bound_required	403	This party requires a device-bound passkey for sealing
invitation_invalid	410	Invitation is not valid
invitation_email_mismatch	403	Sign in with the email address the invitation was sent to
domain_claimed	409	This email domain belongs to an existing party
assembly_pending	409	This AI company’s setup is not complete
agreement_required	403	The AI-company Terms in force must be accepted first
challenge_invalid	400	Challenge is unknown, expired or already used
registration_invalid	400	Passkey registration is not valid
assertion_invalid	401	Passkey assertion is not valid
passkey_test_failed	400	The new passkey failed its test signature and was not saved
credential_unknown	401	Passkey is not registered or has been revoked
credential_exists	409	Passkey is already registered
mint_assertion_missing	403	Sign-in token has no recent mint assertion
session_invalid	401	The session is not bound to a live MasterDB sign-in; sign in again

Records and seals

Code	Status	Meaning
record_invalid	422	Record is not valid
json_invalid	400	Body is not one strict JSON value
record_too_large	413	Record is too large
duplicate_key	422	Object has a duplicate key
depth_exceeded	422	Nesting is too deep
string_too_long	422	String is too long
too_many_keys	422	Object has too many keys
control_character	422	String contains a control character
zero_width_character	422	String contains a zero-width space or U+FEFF
bidi_override	422	String contains a bidirectional override
not_nfc	422	String is not in Unicode Normalization Form C
invalid_utf8	400	Body is not valid UTF-8
bom_present	400	Body starts with a byte-order mark
number_invalid	422	Number is outside the range every parser agrees on
money_not_string	422	Money must be a decimal string
money_invalid	422	Money string is not a valid decimal
schema_missing	422	Record has no top-level schema field
schema_invalid	422	Record schema field is not valid
not_canonical	422	Bytes are not in the canonical form
seal_invalid	422	Seal does not verify
seal_key_unknown	422	Seal names a key that is not registered
seal_payload_type	422	Envelope carries the wrong payload type
seal_hash_mismatch	422	Seal hash does not match the record bytes
seal_time_skew	422	sealed_at is too far from the time of receipt
seq_not_increasing	409	Batch sequence number is not greater than the last accepted
price_country_not_published	422	A price names a country the record is not published in
unsafe_url	422	URL points at a private or unsafe address
field_required	422	A required field is missing
plain_text_required	422	Text must be plain text
role_address_required	422	A published contact must be a role address, not a person
personal_data	422	Freeform text must not carry personal data
country_invalid	422	Not a country code in the platform vocabulary
currency_invalid	422	Not a currency code in the platform vocabulary
language_invalid	422	Not a language in the platform vocabulary
vocabulary_invalid	422	Value is not in the controlled vocabulary
seal_required	422	A seal is required
mandate_required	403	The signing key has no live publishing mandate
mandate_scope	403	The mandate does not cover this record type or country
draft_revision_conflict	409	The draft has changed since you read it
scope_violation	422	Text names another company or brand, or directs how other sources are treated
url_flagged	422	URL is flagged as unsafe
display_domain_mismatch	422	display_domain is not the destination host
image_type_refused	422	Only JPEG, PNG and WebP images are accepted
image_invalid	422	Image could not be decoded within the limits
source_not_allowed	403	The request comes from outside the mandate’s source allow-list
domain_unproven	422	An endpoint domain has no live proof of control
verification_level_insufficient	403	This action is not available to this party until its verification is complete: finish it, then try again
screening_not_passed	403	A check this action needs has not passed: try again later, and if it still has not passed, get in touch with us

Portal

Code	Status	Meaning
verification_locked	409	Locked while verification is submitted or decided
feature_not_enabled	403	This feature is not enabled
prf_unsupported	422	The passkey does not support the PRF extension

Ads and money

Code	Status	Meaning
budget_exhausted	409	Budget exhausted
window_expired	409	Confirmation window has expired
token_invalid	400	Token is not valid
token_reused	409	Token has already been confirmed
allowance_exhausted	402	Query allowance exhausted

API conventions

Code	Status	Meaning
idempotency_key_missing	400	Idempotency-Key header is required
idempotency_key_invalid	400	Idempotency-Key header is not valid
idempotency_key_reused	422	Idempotency-Key was used with a different request
idempotency_in_progress	409	A request with this Idempotency-Key is in progress
unauthenticated	401	Not signed in
step_up_required	403	A stronger sign-in is required for this action
forbidden	403	Not permitted
not_found	404	Not found
conflict	409	Conflict
rate_limited	429	Too many requests
internal	500	Internal error
not_implemented	501	Not implemented
unavailable	503	Temporarily unavailable