Error Responses

HTTP Status Codes

If a call to a Wristband API fails, the response will include a 4xx or 5xx HTTP status code.

4xx indicates an issue with the request.
5xx indicates an error on Wristband's servers.

In both cases, the response body includes a JSON object with details about the error. The JSON object will be one of two types:

Base Error
Constraint Violations Error

In the following sections, we'll go over the differences between the two types of error objects.

Base Error Object

This is the default error object, and it can be returned for both 4xx and 5xx HTTP status codes.

Base Error Object Fields

Name	Type	Description
type	String	The type of the error object. This value will always be `base_error`.
code	String	A distinct code representing the error that occurred.
message	String	A human-readable message describing the error.
ticket	String	String used internally by Wristband to correlate error responses to server-side requests.

Example Base Error Response

The following is an example of a Base Error returned when calling the Get User API with an identifier that does not match an existing user.

HTTP/2 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "type": "base_error",
  "code": "user_not_found",
  "message": "User [abc123] could not be found",
  "ticket": "v1c7nblicpvqia7fia8r5d2qeu"
}

Constraint Violations Error Object

Constraint Violations Error objects are returned when issues are linked to specific parts of the HTTP request, such as a request body field, query parameter, path parameter, or header. A Constraint Violations Error object has the same structure as a Base Error object, except it has an additional violations field.

Constraint Violations Error Object Fields

Name	Type	Description
type	String	The type of the error object. This value will always be `constraint_violations_error`.
code	String	A distinct code representing the error that occurred. The code will be one of the following: - `message_body_constraint_violations`: Returned if the violations correspond to the request message body fields. - `request_constraint_violations`: Returned when the violations relate to parts of the HTTP request other than the body, such as query parameters, path parameters, or headers.
message	String	A human-readable message describing the error.
ticket	String	String used internally by Wristband support to correlate error responses to server-side requests.
violations	Map<String, List<ConstraintViolationDetails>>	A map where each key is the path to the part of the request that violated the constraint, and each value is a `ConstraintViolationDetails` object describing the violation.

Constraint Violation Details Object Fields

Name	Type	Description
code	String	Error code indicating the issue with the request value.
constraintAttributes	Map<String, String>	A map containing metadata about the violated constraint. Each key is a constraint attribute name, and each value is the attribute's assigned value, represented as a string. Note, for some violations, the `constraintAttribute` field may be undefined if there's no additional metadata associated with the code.

Example Constraint Violations Error Response

To help better understand the structure of a Constraint Violation Error, consider a request to the Create User API with an email value exceeding the 200-character limit. The resulting error response would appear as follows:

HTTP/2 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "type": "constraint_violations_error",
  "code": "message_body_constraint_violations",
  "message": "Field violations detected while trying to create a user",
  "ticket": "jgqgau2nj4eobeaje6m4jhoop8",
  "violations": {
    "email": [{
      "code": "too_long",
      "constraintAttributes": {
        "maxLength": "200"
      }
    }]
  }
}

If we look at the violations, we can see it contains one entry for the user email field. The code of too_long indicates that the email value we provided exceeded the max allowed length. Furthermore, the constraintAttributes field includes a maxLength attribute set to 200, showing that the email field cannot exceed 200 characters.

ℹ️
Nested Fields
If a violation occurs on a nested field, the key will show the full path to the field, using periods (.) as field delimiters. For example, if the Create Identity Provider API was called with an invalid protocol type, the violation key would be protocol.type.

Constraint Violation Codes

Below is a table containing descriptions of all constraint violation codes.

Code	Description
after_end_date	Indicates that a start date was after its corresponding end date.
application_redirect_urls_not_supported	Indicates that a request was made to resolve an application redirect URL for an identity provider, but that identity provider does not support application redirect URLs.
blank	Indicates that a string was left blank when a value was required.
consumer_tenant_id_not_allowed	Indicates that the Microsoft tenant ID was equal to the consumer tenant ID, when it was required to be an organization tenant ID.
contained_disallowed_element	Indicates that a collection contained an element that is not allowed.
contained_invalid_field_name	Indicates that the specified object field name is not valid.
contained_nested_arrays	Indicates that an object contained nested arrays, which are not allowed.
digit_not_present	Indicates that a password did not contain a digit when digits are required.
disabled	Indicates that the referenced entity is disabled when it is required to be enabled.
disallowed_enum	Indicates that the specified enum value is not allowed.
duplicate_elements	Indicates that a collection contains duplicate elements when they are required to be unique.
duplicate_wildcards	Indicates that duplicate wildcards were found within a domain name.
duration_greater_than	Indicates that a duration was greater than the maximum allowed value.
duration_less_than	Indicates that a duration was less than the minimum allowed value.
email_domain_not_allowed	Indicates that an email has a domain that is not allowed.
email_domain_not_verified	Indicates that the specified domain of an email address was not verified.
email_not_permitted	Indicates that the specified email address is valid but not permitted.
email_not_verified	Indicates that an email could not be sent because the user's email has not been verified.
email_unchanged	Indicates that an email being changed was not different from its previous value.
email_value_not_allowed	Indicates that a value was an email when non-email values are required.
enablement_not_allowed	Indicates that an attempt was made to enable a feature that is not permitted to be enabled.
empty	Indicates that a collection was empty when it is required to contain at least one element.
expired	Indicates that an ephemeral token or code has expired.
failed_regex_match	Indicates that a string value did not match a required regex pattern.
future	Indicates that a time or date value references the future when it should reference the past.
greater_than	Indicates that a number was greater than the maximum allowed value.
greater_than_refresh_token_absolute_lifetime	Indicates that a client's refresh token idle lifetime was greater than its absolute lifetime.
greater_than_absolute_timeout	Indicates that an entity's idle timeout is greater than its absolute timeout.
illegal_domain_suffix	Indicates that a domain name contained an illegal suffix.
illegal_role_assignment	Indicates that an attempt was made to assign a role to an entity that is not permitted to have that role assigned to it.
immutable	Indicates an attempt to modify a field that is immutable.
inactive	Indicates that the referenced entity is inactive when an active one is required.
invalid_action_link_lifetime_unit	Indicates that an email action link lifetime unit was invalid.
invalid_auth_factor_combination	Indicates that an invalid combination of auth factors was specified.
invalid_auth_session_code	Indicates that the auth session code was invalid
invalid_auth_session_token	Indicates that the session token was invalid.
invalid_authorization_code	Indicates that the authorization code was invalid.
invalid_authorization_request_token	Indicates that the authorization request token was invalid.
invalid_client_type	Indicates that a specified client did not have the correct type.
invalid_code_point	Indicates that a Unicode string contained an invalid code point.
invalid_date	Indicates that a string was not a valid ISO 8601 representation of a date.
invalid_date_time	Indicates that a string was not a valid ISO 8601 representation of a datetime.
invalid_directionality	Indicates that a Unicode string violated a directionality rule.
invalid_display_name_for_identity_provider_type	Indicates that the given display name was not valid for the specified identity provider type.
invalid_domain_name	Indicates that a string was not a valid domain name.
invalid_domain_name_label	Indicates that a string was not a valid domain name label.
invalid_duration	Indicates that a string was not a valid ISO 8601 duration.
invalid_e164_phone_number	Indicates that a string was not a valid E.164 phone number
invalid_email	Indicates that a string was not a valid email address.
invalid_email_auth_code	Indicates that the given email auth code was invalid.
invalid_epoch_timestamp	Indicates that a number could not be converted to a valid epoch timestamp.
invalid_external_idp_auth_code	Indicates that a provided external IdP auth code was invalid.
invalid_identity_provider_type	Indicates that the specified identity provider had the wrong type.
invalid_invite_code	Indicates that the provided invite code was invalid.
invalid_ip_address	Indicates that a string was not a valid IP address.
invalid_locale	Indicates that a string was not a valid BCP 47 language tag.
invalid_name_for_identity_provider_type	Indicates that the given identity provider name was not valid for the specified identity provider type.
invalid_owner_type	Indicates that the owner type associated with an entity is not allowed.
invalid_password_reset_code	Indicates that a password reset code was invalid.
invalid_path_expression	Indicates that a string was not a valid path expression composed of field names delimited by periods (`.`).
invalid_pem_certificate	Indicates that a string value was not a valid PEM certificate.
invalid_phone_number	Indicates that a string was not a valid phone number.
invalid_private_key	Indicates that a private key did not have a valid PEM format.
invalid_request_code	Indicates that a provided request code was invalid.
invalid_role	Indicates that a specified role was not valid for the operation.
invalid_scope	Indicates that a string was not a valid OAuth 2 scope.
invalid_semantic_version	Indicates that a string was not a valid semantic version.
invalid_status_transition	Indicates that an attempt was made to transition an entity to an invalid status.
invalid_time_zone	Indicates that a string was not a valid IANA time zone.
invalid_token	Indicates that the provided token is not valid.
invalid_url	Indicates that a string was not a valid URL.
invalid_url_authority	Indicates that a string contained an invalid URL authority.
invalid_url_path	Indicates that a string contained an invalid URL path.
invalid_url_query	Indicates that a string contained an invalid URL query string.
invalid_url_scheme	Indicates that a string contained an invalid URL scheme.
invalid_verification_code	Indicates that a verification code was invalid.
invalid_wildcard_placement	Indicates that a wildcard was placed incorrectly within a domain name.
less_than	Indicates that a number was less than the minimum allowed value.
less_than_idle_timeout	Indicates that an entity's absolute timeout was less than its idle timeout.
less_than_refresh_token_idle_lifetime	Indicates that a client's refresh token absolute lifetime was less than its idle lifetime.
lowercase_char_not_present	Indicates that a password did not contain a lowercase character when one is required.
max_byte_length_exceeded	Indicates that a field's max byte length was exceeded.
max_field_count_exceeded	Indicates that an object contains more fields than the allowed maximum.
max_nesting_depth_exceeded	Indicates that an object contains nested objects that exceed the maximum allowed nesting depth.
missing_required_element	Indicates that a collection is missing an element that is required to be present in the collection.
not_active	Indicates that a referenced entity is not active when it is required to be active.
not_alphanumeric	Indicates that a string contained non-alphanumeric characters when only alphanumeric characters are allowed.
not_false	Indicates that a boolean value was `true` when it was required to be `false`.
not_empty	Indicates that a collection was not empty when it was required to be empty.
not_found	Indicates that a referenced entity does not exist.
not_json_object	Indicates that a string was not a valid JSON object.
not_null	Indicates that a value was not null when it should have been null.
not_pending_activation	Indicates that a user did not have a status of pending activation.
not_subdomain_of_public_suffix	Indicates that the specified domain name was not a subdomain of a public suffix.
not_true	Indicates that a boolean value was `false` when it was required to be `true`.
not_undefined	Indicates that a value was not undefined when it should have been undefined.
not_unique	Indicates that the specified value violates a unique constraint. For example, this error can occur when you attempt to create a tenant with a name that's already in use by another tenant within the same application.
null	Indicates that a value was null when a non-null value was required.
password_breached	Indicates that a specified password has been detected in a breached data set.
password_unchanged	Indicates that a password being changed was not different from its previous value.
password_verification_not_enabled	Indicates that an identity provider supports password verification as an authentication factor, but does not have it enabled.
password_verification_not_supported	Indicates that an identity provider does not support password verification as an authentication factor.
past_or_present	Indicates that a time or date value references the past or present when it should reference the future.
pending_activation	Indicates that the user is pending activation when a non-pending activation state is required.
redirect_urls_not_supported	Indicates that a request was made to resolve a redirect URL for an identity provider, but that identity provider does not support redirect URLs.
role_not_found	Indicates that a specified role does not exist.
size_greater_than	Indicates the size of a collection is greater than the maximum allowed size.
special_char_not_present	Indicates that a password did not contain a special character when special characters are required.
phone_number_value_not_allowed	Indicates that a value was a phone number when non-phone number values are required.
too_far_into_past	Indicates that a date or time value is too far into the past.
too_far_into_future	Indicates that a date or time value is too far into the future.
too_long	Indicates that a string value is too long.
too_short	Indicates that a string value is too short.
type_disallowed_for_global_tenant	Indicates that an entity type is not allowed for a global tenant.
undefined	Indicates that a value was undefined when a value is required.
unknown	Indicates that an unknown enum value was provided.
unsupported_destination_attribute	Indicates that the IdP does not support the provided destination attribute.
unsupported_identity_provider_name	Indicates that the provided identity provider name does not reference a supported identity provider.
unsupported_path_expression	Indicates that the provided path expression is not supported.
uppercase_char_not_present	Indicates that a password did not contain an uppercase character when one is required.
url_contained_fragment	Indicates that a URL contained a fragment when fragments are not allowed.
url_contained_http_scheme	Indicates that a URL contained an HTTP scheme instead of an HTTPS scheme.
url_contained_ip_address	Indicates that a URL contained an IP address instead of a domain name as the host.
url_contained_loopback_address	Indicates that a URL contained a loopback address when loopback addresses are not allowed.
url_contained_query_parameters	Indicates that a URL contained query parameters when query parameters are not allowed.
url_contained_user_info	Indicates that a URL contained user info when user info is not allowed.
url_domain_name_too_long	Indicates that the URL's domain name is too long.
wildcard_domain_suffix_too_long	Indicates that a wildcard domain suffix was too long.
wildcard_not_allowed_in_ip_address	Indicates that a wildcard was used inside an IP address.

Constraint Violation Attributes

Below is a table containing descriptions of all constraint violation attributes.

Attribute Name	Description
allowedElements	An attribute representing a list of elements that are allowed to be in a collection.
allowedValues	An attribute representing a list of allowed values.
disallowedValues	An attribute representing a list of disallowed values.
invalidFieldName	An attribute representing the field name that was invalid.
maxByteLength	An attribute representing the maximum number of bytes a field value can have.
maxFieldCount	An attribute representing the maximum number of fields an object can have.
maxNestingDepth	An attribute representing the maximum allowed nesting depth of an object.
maxValue	An attribute representing the maximum value of a number.
maxLength	An attribute representing the maximum length of a string.
maxSize	An attribute representing the maximum size of a collection.
maxDuration	An attribute representing the maximum value of a duration.
maxFutureOffset	An attribute representing the maximum future offset of a time value.
maxPastOffset	An attribute representing the maximum past offset of a time value.
minValue	An attribute representing the minimum value of a number.
minLength	An attribute representing the minimum length of a string.
minDuration	An attribute representing the minimum value of a duration.
regexPattern	An attribute representing a regex pattern that a string must match.
requiredElements	An attribute representing a set of elements that are required to be present in a collection.

HTTP Status Codes

Base Error Object

Example Base Error Response

Constraint Violations Error Object

Example Constraint Violations Error Response

ℹ️Nested Fields

Constraint Violation Codes

Constraint Violation Attributes

ℹ️
Nested Fields