Skip to main content

​
Overview

The Chat Server API returns structured error responses when requests fail. All errors follow a consistent format using the ErrorResponse DTO structure.

​
Error response structure

​
message
string
required
A human-readable error message describing what went wrong

​
Example error response

{
  "message": "User with name 'john_doe' already exists."
}

​
HTTP status codes

The API uses the following HTTP status codes to indicate the type of error:

​
400 Bad Request

Returned when the request is malformed or contains invalid data. Common causes include:
  • Invalid username or password format
  • Username or password validation failures
  • Attempting to perform an invalid relationship operation
  • Relationship does not exist

​
401 Unauthorized

Returned when authentication fails or is required but not provided:
  • Authorization token was not provided
  • Authorization token is invalid or expired
  • Password confirmation incorrect (for sensitive operations like account deletion)

​
404 Not Found

Returned when a requested resource does not exist.

​
409 Conflict

Returned when the request conflicts with the current state of the server:
  • Username already exists during registration

​
Exception types

The following exception types are handled by the API, organized by controller:

​
User exceptions

Status Code: 409 ConflictThrown when: A user attempts to register with a username that already existsExample message:
{
  "message": "User with name 'john_doe' already exists."
}
Status Code: 400 Bad RequestThrown when: A password is shorter than the minimum required length (6 characters)Example message:
{
  "message": "Password must be longer than 6 characters."
}
Status Code: 400 Bad RequestThrown when: A username is shorter than the minimum required length (2 characters)Example message:
{
  "message": "Username 'a' must be longer than 2 characters."
}
Status Code: 400 Bad RequestThrown when: A username exceeds the maximum allowed length (8 characters)Example message:
{
  "message": "Username 'verylongusername' must be longer than 8 characters."
}
Status Code: 400 Bad RequestThrown when: Login credentials are incorrectExample message:
{
  "message": "Username or password is incorrect."
}
Status Code: 401 UnauthorizedThrown when: A user attempts to access a protected resource without valid authenticationExample message:
{
  "message": "You are not authorized to access this resource at this time."
}
Status Code: 401 UnauthorizedThrown when: Password confirmation fails during account deletionExample message:
{
  "message": "Password incorrect."
}

​
Relationship exceptions

Status Code: 400 Bad RequestThrown when: Attempting to send a friend request to a user that doesn’t existExample message:
{
  "message": "User with username \"nonexistent_user\" doesn't exist."
}
Status Code: 400 Bad RequestThrown when: Attempting to send a friend request to yourselfExample message:
{
  "message": "You can't friend yourself. Try making friends :)"
}
Status Code: 400 Bad RequestThrown when: Attempting to create a relationship with a user you’re already friends withExample message:
{
  "message": "You are already friends with \"jane_doe\""
}
Status Code: 400 Bad RequestThrown when: Attempting to send another friend request when one is already pendingExample message:
{
  "message": "You can't create another outgoing request for \"jane_doe\""
}
Status Code: 400 Bad RequestThrown when: Attempting to delete or modify a relationship that doesn’t existExample message:
{
  "message": "You do not currently have an outgoing, incoming, or active relationship with \"jane_doe\""
}

​
Authentication exceptions

Status Code: VariesThrown when: Spring Security authentication failsHandled by: GlobalExceptionController (UserController.java:167-171, UserController.java:179-183, RelationshipController.java:168-172, etc.)This is a generic Spring Security exception that covers various authentication failures. Specific error messages depend on the type of authentication failure.

​
Error handling locations

Error handlers are implemented in the following controller files:
  • GlobalExceptionController.java - Handles global AuthenticationException from Spring Security
  • UserController.java - Handles user-related exceptions (registration, login, account management)
  • RelationshipController.java - Handles relationship-related exceptions (friend requests, relationship management)

​
Best practices

When handling errors in your client application:
  1. Always check the HTTP status code first to determine the type of error
  2. Display the message field to users for human-readable error information
  3. Implement appropriate retry logic for 5xx errors (server errors)
  4. For 401 errors, redirect users to login or refresh authentication tokens
  5. For 400 errors, validate user input on the client side to prevent unnecessary API calls

Build docs developers (and LLMs) love

Get started for freeTalk to us