Skip to main content

FieldViolation

A single field of the request that was rejected, and why.

fieldstringrequired

Path of the offending field, in request-body naming. Array entries are indexed and map entries are keyed, e.g. purchase_url, allowed_publish_urls[2], custom_fields["asset_id"].string_value.

reasonstringrequired

Machine-readable cause of the violation — the value to branch on:

  • REQUIRED: A field the request cannot omit was not provided
  • INVALID_TYPE: The value has the wrong JSON type for the field
  • INVALID_FORMAT: The value has the right type but is not well-formed for the field, e.g. an unparsable URL or timestamp, or a fixed-length value of the wrong length
  • UNSUPPORTED_SCHEME: A URL uses a scheme the field does not accept (only https is accepted)
  • FORBIDDEN_USERINFO: A URL carries userinfo (user:password@), which is never accepted
  • FORBIDDEN_HOST: A URL points at a host the field does not accept, such as an IP literal or localhost
  • TOO_LONG: The value is longer than the field allows
  • TOO_MANY: The list or map holds more entries than the field allows
  • INVALID_CHARACTERS: The value contains characters the field does not accept, such as control characters
  • UNKNOWN_VALUE: The value is not one of the values the field defines, e.g. an unknown share_state
  • NOT_ALLOWED_HERE: The field is well-formed but not allowed in this combination, e.g. a distribution field on a private Record
  • EXACTLY_ONE_REQUIRED: Exactly one of a group of mutually exclusive properties must be set, e.g. the typed value of a custom_fields entry
  • UNKNOWN_FIELD: The body carries a field the endpoint does not define — commonly a misspelling, or a camelCase spelling of a snake_case field
  • EMPTY: The value is present but empty where a value is required
  • INVALID_PATTERN: A URL pattern is malformed and cannot be interpreted

The set is closed, but it may be extended with new reasons. Treat a reason you do not recognise as a generic validation failure rather than failing hard.

Possible values: [REQUIRED, INVALID_TYPE, INVALID_FORMAT, UNSUPPORTED_SCHEME, FORBIDDEN_USERINFO, FORBIDDEN_HOST, TOO_LONG, TOO_MANY, INVALID_CHARACTERS, UNKNOWN_VALUE, NOT_ALLOWED_HERE, EXACTLY_ONE_REQUIRED, UNKNOWN_FIELD, EMPTY, INVALID_PATTERN]

descriptionstringrequired

Human-readable explanation of this violation, safe to log and to show to a developer.

It may name the offending field or map key and state the limit that applies, but it never echoes the value that was submitted. English, not localized, and the wording is not stable across releases — never parse or branch on it.

FieldViolation
{
  "field": "string",
  "reason": "REQUIRED",
  "description": "string"
}