General errors

An error response from the Thalamus API is composed of two main parts: the HTTP status code and an error message in the response body.

Thalamus uses a default error message format, but an alternative, more structured format called Error Version 2 can be requested.

---

Default Error Format

400 Bad Request

This is the most common error response. If a request fails validation, Thalamus will respond with an HTTP 400 status and a JSON body detailing all the errors. Each error has a code that can be used by the client application to display a translated message to the user.

General Errors

These errors relate to the overall state or context of the request.

Error Code	Description
PartyAlreadyLoggedin	Occurs when trying to perform an action that requires a user to be logged out (e.g., Register or Request Reset Password), but a user is already logged in.
InvalidToken	Occurs when trying to reset a password with an invalid or expired token.
CredentialAlreadyExists	Occurs when trying to register a consumer that already exists.
InvalidJson	Occurs when the JSON in the request body is malformed.
UnsupportedMediaType	Occurs when trying to provide a media type that is not supported.

Field-Specific Errors

These errors relate to the value of a specific field in the request body.

Error Code	Description
Required	A required field is missing from the request.
NotEditable	An attempt was made to change a field that is not editable.
InvalidFormat	The value for a field is in the wrong format (e.g., sending a string for a number field).
InvalidId	A field references an entity ID that does not exist.
InvalidName	The value contains illegal characters. Name fields allow letters and spaces (up to 100 characters).
InvalidCode	The value contains illegal characters. Code fields allow letters and numbers (up to 100 characters).
InvalidMail	The value is not a valid email address.
InvalidPhoneNumber	The phone number format is invalid. Must be digits, parentheses, and hyphens (up to 10 digits).
InvalidDateFormat	The value is not a valid date.
BeforeTodayRequired	Occurs when trying to provide a present or future date in a field that requires a past date.
InvalidPassword	The password does not meet the requirements (letters and numbers, 4-100 characters).
NotMatch	Occurs in three cases: 1) The old password does not match the stored password. 2) The new password does not match the confirmation password. 3) A profile identifier does not match the principal's identifier.
EqualsOldPassword	The new password is the same as the old password.

Error Key Structure

The keys in the errors object are structured to show exactly which field caused the error, reflecting the navigation path in the JSON body.

For example, given the following request JSON:

{
  "consumer": {
    "activeConsumer": true,
    "preferedBrandId": -1
  }
}

If the preferedBrandId is invalid, the error key will be consumer.preferedBrandId. The response would be:

{
  "errors": {
    "consumer.preferedBrandId": "InvalidId"
  }
}

Other Response Codes

Code	Status Name	Description
401 Unauthorized	Unauthorized	The user is not authorized to perform the requested action (e.g., not logged in).
404 Not Found	Not Found	The requested resource or URL could not be found.
415 Unsupported Media Type	Unsupported Media Type	The Content-Type of the request is not supported by the endpoint.
500 Internal Server Error	Internal Server Error	An unexpected error occurred on the server side.

---

Error Version 2

This is an alternative error format that provides more structured information.

Structure

The error object has three attributes:

• code: The machine-readable error code (e.g., Required).

• message: A human-readable error message (e.g., Field Required).

• field: (Optional) The specific field that caused the error (e.g., email).

JSON

{
  "errors": [
    {
      "code": "Required",
      "message": "Field Required",
      "field": "email"
    }
  ]
}

{
  "errors": [
    {
      "code": "InternalServerError",
      "message": "Internal Server Error"
    }
  ]
}

How to Trigger

To receive this error format, you must send the ev=2 parameter in the request URL's query string.

https://<server-url>/api/v4/me?ev=2