Error Responses

Learn about the different error responses returned from Wristband's APIs.

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

NameTypeDescription
typeStringThe type of the error object. This value will always be base_error.
codeStringA distinct code representing the error that occurred.
messageStringA human-readable message describing the error.
ticketStringString 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

NameTypeDescription
typeStringThe type of the error object. This value will always be constraint_violations_error.
codeStringA 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.
messageStringA human-readable message describing the error.
ticketStringString used internally by Wristband support to correlate error responses to server-side requests.
violationsMap<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

NameTypeDescription
codeStringError code indicating the issue with the request value.
constraintAttributesMap<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.

CodeDescription
blankIndicates that a string was left blank when a value was required.
contained_disallowed_elementIndicates that a collection contained an element that is not allowed.
contained_invalid_field_nameIndicates that the specified object field name is not valid.
contained_nested_arraysIndicates that an object contained nested arrays, which are not allowed.
digit_not_presentIndicates that a password did not contain a digit, when digits are required.
disabledIndicates that the referenced entity is disabled when it is required to be enabled.
disallowed_enumIndicates that the specified enum value is not allowed.
duplicate_elementsIndicates that a collection contained duplicate elements, when they are required to be unique.
duration_greater_thanIndicates that a duration was greater than the maximum allowed value.
duration_less_thanIndicates that a duration was less than the minimum allowed value.
email_value_not_allowedIndicates that a value was an email when non-email values are required.
emptyIndicates that a collection was empty when it is required to contain at least one element.
expiredIndicates that an ephemeral token or code has expired.
failed_regex_matchIndicates that a string value did not match a required regex pattern.
greater_thanIndicates that a number was greater than the maximum allowed value.
illegal_domain_suffixIndicates that a domain name contained an illegal suffix.
immutableIndicates an attempt to modify a field that is immutable.
inactiveIndicates that the referenced entity is inactive when an active one is required.
invalid_code_pointIndicates that a Unicode string contained an invalid code point.
invalid_dateIndicates that a string was not a valid ISO 8601 representation of a date.
invalid_date_timeIndicates that a string was not a valid ISO 8601 representation of a datetime.
invalid_directionalityIndicates that a Unicode string violated a directionality rule.
invalid_domain_nameIndicates that a string was not a valid domain name.
invalid_domain_name_labelIndicates that a string was not a valid domain name label.
invalid_durationIndicates that a string was not a valid ISO 8601 duration.
invalid_e164_phone_numberIndicates that a string was not a valid E.164 phone number
invalid_emailIndicates that a string was not a valid email address.
invalid_epoch_timestampIndicates that a number could not be converted to a valid epoch timestamp.
invalid_ip_addressIndicates that a string was not a valid IP address.
invalid_localeIndicates that a string was not a valid BCP 47 language tag.
invalid_path_expressionIndicates that a string was not a valid path expression composed of field names delimited by periods (.).
invalid_phone_numberIndicates that a string was not a valid phone number.
invalid_semantic_versionIndicates that a string was not a valid semantic version.
invalid_time_zoneIndicates that a string was not a valid IANA time zone.
invalid_urlIndicates that a string was not a valid URL.
invalid_url_authorityIndicates that a string contained an invalid URL authority.
invalid_url_pathIndicates that a string contained an invalid URL path.
invalid_url_queryIndicates that a string contained an invalid URL query string.
invalid_url_schemeIndicates that a string contained an invalid URL scheme.
less_thanIndicates that a number was less than the minimum allowed value.
lowercase_char_not_presentIndicates that a password did not contain a lowercase character when one is required.
max_byte_length_exceededIndicates that a field's max byte length was exceeded.
max_field_count_exceededIndicates that an object contains more fields than the allowed maximum.
max_nesting_depth_exceededIndicates that an object contains nested objects that exceed the maximum allowed nesting depth.
missing_required_elementIndicates that a collection is missing an element that is required to be present in the collection.
not_activeIndicates that a referenced entity is not active when it is required to be active.
not_alphanumericIndicates that a string contained non-alphanumeric characters when only alphanumeric characters are allowed.
not_falseIndicates that a boolean value was true when it was required to be false.
not_emptyIndicates that a collection was not empty when it was required to be empty.
not_foundIndicates that a referenced entity does not exist.
not_json_objectIndicates that a string was not a valid JSON object.
not_nullIndicates that a value was not null when it should have been null.
not_subdomain_of_public_suffixIndicates that the specified domain name was not a subdomain of a public suffix.
not_trueIndicates that a boolean value was false when it was required to be true.
not_undefinedIndicates that a value was not undefined when it should have been undefined.
not_uniqueIndicates 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.
nullIndicates that a value was null when a non-null value was required.
futureIndicates that a time or date value references the future when it should reference the past.
password_breachedIndicates that a specified password has been detected in a breached data set.
past_or_presentIndicates that a time or date value references the past or present when it should reference the future.
size_greater_thanIndicates the size of a collection is greater than the maximum allowed size.
special_char_not_presentIndicates that a password did not contain a special character when special characters are required.
phone_number_value_not_allowedIndicates that a value was a phone number when non-phone number values are required.
too_far_into_pastIndicates that a date or time value is too far into the past.
too_far_into_futureIndicates that a date or time value is too far into the future.
too_longIndicates that a string value is too long.
too_shortIndicates that a string value is too short.
undefinedIndicates that a value was undefined when a value is required.
unknownIndicates that an unknown enum value was provided.
uppercase_char_not_presentIndicates that a password did not contain an uppercase character when one is required.
url_contained_fragmentIndicates that a URL contained a fragment when fragments are not allowed.
url_contained_http_schemeIndicates that a URL contained an HTTP scheme instead of an HTTPS scheme.
url_contained_ip_addressIndicates that a URL contained an IP address instead of a domain name as the host.
url_contained_loopback_addressIndicates that a URL contained a loopback address when loopback addresses are not allowed.
url_contained_query_parametersIndicates that a URL contained query parameters when query parameters are not allowed.
url_contained_user_infoIndicates that a URL contained user info when user info is not allowed.
url_domain_name_too_longIndicates that the URL's domain name is too long.