Skip to main content
The User Management API returns errors using the RFC 7807 Problem Details standard format. All error responses follow this consistent structure.

​
Error Response Structure

​
type
string
A URI reference that identifies the problem typeExample: about:blank
​
title
string
A short, human-readable summary of the problem typeExample: Validation Failed
​
status
integer
The HTTP status code for this occurrence of the problemExample: 400
​
detail
string
A human-readable explanation specific to this occurrence of the problemExample: username: username is required
​
timestamp
string (ISO 8601 DateTime)
The timestamp when the error occurredExample: 2024-01-15T10:30:00
​
[additional properties]
varies
Additional context-specific properties may be included based on the error typeExample: userId for User Not Found errors

​
Common Error Types

​
Validation Failed (400 Bad Request)

Returned when request validation fails. The detail field contains information about which fields failed validation. Example: Missing required field 
{
  "type": "about:blank",
  "title": "Validation Failed",
  "status": 400,
  "detail": "username: username is required",
  "timestamp": "2024-01-15T10:30:00"
}
Example: Multiple validation errors 
{
  "type": "about:blank",
  "title": "Validation Failed",
  "status": 400,
  "detail": "username: username must be between 3 and 50 characters; email: email must be a valid email address",
  "timestamp": "2024-01-15T10:30:00"
}
Example: Invalid email format 
{
  "type": "about:blank",
  "title": "Validation Failed",
  "status": 400,
  "detail": "email: email must be a valid email address",
  "timestamp": "2024-01-15T10:30:00"
}

​
User Not Found (404 Not Found)

Returned when attempting to access or modify a user that doesn’t exist. Includes the userId property. 
{
  "type": "about:blank",
  "title": "User Not Found",
  "status": 404,
  "detail": "User with id 0f4df2de-fffb-4a24-9891-381ecf4f0f87 not found",
  "userId": "0f4df2de-fffb-4a24-9891-381ecf4f0f87",
  "timestamp": "2024-01-15T10:30:00"
}

​
User Already Exists (409 Conflict)

Returned when attempting to register a user with a username or email that already exists in the system. 
{
  "type": "about:blank",
  "title": "User Already Exists",
  "status": 409,
  "detail": "User with username 'jdoe' already exists",
  "timestamp": "2024-01-15T10:30:00"
}

​
Internal Server Error (500)

Returned when an unexpected error occurs on the server. 
{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "timestamp": "2024-01-15T10:30:00"
}

​
Validation Rules Summary

​
Username

  • Required (cannot be blank)
  • Length: 3-50 characters
  • Must be unique
  • Immutable after creation

​
Email

  • Required (cannot be blank)
  • Must be valid email format
  • Must be unique

​
First Name / Last Name

  • Required (cannot be blank)
  • Maximum length: 100 characters

​
Role

  • Required (cannot be null)
  • Must be one of: ADMIN, USER, GUEST

Build docs developers (and LLMs) love

Get started for freeTalk to us