Documentation Index
Fetch the complete documentation index at: https://docs.7331.org/llms.txt
Use this file to discover all available pages before exploring further.
The API uses standard HTTP status codes and returns consistent error responses. All error responses include a correlation_id for tracing issues in server logs.
Every error response includes at minimum:
{
"error": "<human-readable message>",
"correlation_id": "<uuid>"
}
| Field | Type | Description |
|---|
error | string | A human-readable error message. Internal details are never exposed to clients. |
correlation_id | string | A UUID for tracing the request in server logs. |
HTTP Status Codes
| Code | Description | Example error value |
|---|
200 | Success | — |
400 | Bad request — invalid parameters or failed validation | "Invalid request" |
401 | Unauthorized — missing or invalid authentication | "Authentication required" |
403 | Forbidden — insufficient permissions or account restricted | "Access denied" |
404 | Not found — resource doesn’t exist | "User not found" |
409 | Conflict — resource already exists or state conflict | "Entity already exists" |
429 | Rate limited — too many requests | "Too many requests" |
500 | Internal server error | "Internal server error" |
Error Examples
400 Bad Request
Validation errors return a user-friendly message describing the first invalid field. For example:
{
"error": "username must be at least 3 characters",
"correlation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}
"username contains invalid characters", "code is required", "name must be at most 50 characters".
401 Unauthorized
{
"error": "Authentication required",
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
403 Forbidden
Permission errors include a specific message indicating what’s required:
{
"error": "Admin access required",
"correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
404 Not Found
{
"error": "User not found",
"correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
409 Conflict
{
"error": "Username is already taken",
"correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
429 Rate Limited
{
"error": "Too many requests",
"correlation_id": "d4e5f6a7-b8c9-0123-defa-234567890123"
}
{
"error": "Too many pending login requests. Please wait for existing codes to expire.",
"correlation_id": "d4e5f6a7-b8c9-0123-defa-234567890123"
}
500 Internal Server Error
{
"error": "Internal server error",
"correlation_id": "e5f6a7b8-c9d0-1234-efab-345678901234"
}
Structured Errors
Some 403 responses include additional context to help the client display actionable information.
Account Banned
{
"error": "Your account has been banned",
"reason": "Terms of service violation",
"correlation_id": "f6a7b8c9-d0e1-2345-fabc-456789012345"
}
Account Timeout
Includes expires_at so the client can show a countdown.
{
"error": "Your account is temporarily restricted",
"reason": "Spamming in chat",
"expires_at": "2026-03-12T20:15:29+00:00",
"correlation_id": "a7b8c9d0-e1f2-3456-abcd-567890123456"
}
| Field | Type | Present | Description |
|---|
reason | string | When available | The reason given by the admin who issued the moderation action. |
expires_at | string | Timeouts only | ISO 8601 timestamp (UTC) when the restriction ends. |
Rate Limiting
Endpoints are rate limited per category. When exceeded, the API returns 429 with the standard error format. Rate limit categories include:
| Category | Applies to |
|---|
| Auth | Login, verify, logout |
| Admin | All /admin/* endpoints |
| Public | User-facing endpoints (search, profile, sessions) |
| Bot | Bot management endpoints |
| Health | Health check endpoints |
