This document provides a comprehensive reference of all error codes in the
Lilith API.
Overview#
The Lilith API uses a standardized error response format compliant with
RFC 7807 (Problem Details for HTTP APIs).
Error Response Structure#
All API errors return a JSON object with the following structure:
json
{
"error": {
"type": "https://docs.lilith.app/errors/auth/invalid_credentials",
"title": "Authentication Failed",
"status": 401,
"detail": "The email or password provided is incorrect.",
"code": "auth.invalid_credentials",
"instance": "/v1/auth/login",
"timestamp": "2024-01-15T10:30:00Z",
"request_id": "req_abc123",
"service": "auth",
"trace_id": "trace_xyz789"
}
}
| Field |
Type |
Description |
type |
string |
URL to error documentation |
title |
string |
Human-readable error title |
status |
number |
HTTP status code |
detail |
string |
Detailed error description |
code |
string |
Machine-readable error code |
instance |
string |
Request URL that generated the error |
timestamp |
string |
ISO 8601 timestamp |
request_id |
string |
Unique request identifier |
service |
string |
Service that generated the error |
trace_id |
string |
Distributed tracing ID (optional) |
errors |
object |
Field-level validation errors (optional) |
retry_after |
number |
Seconds to wait before retry (optional) |
metadata |
object |
Additional context (optional) |
http
x-correlation-id: {correlation_id}
x-error-category: {category}
x-error-severity: {low|medium|high|critical}
retry-after: {seconds}
HTTP Status Codes#
| Code |
Name |
Description |
| 200 |
OK |
Successful response |
| 202 |
Accepted |
Asynchronous processing started |
| 400 |
Bad Request |
Invalid input, validation errors |
| 401 |
Unauthorized |
Authentication required or failed |
| 402 |
Payment Required |
Payment processing failed |
| 403 |
Forbidden |
Insufficient permissions |
| 404 |
Not Found |
Resource not found |
| 409 |
Conflict |
Business logic conflict |
| 410 |
Gone |
Resource no longer available |
| 422 |
Unprocessable Entity |
Semantic validation failed |
| 429 |
Too Many Requests |
Rate limit exceeded |
| 500 |
Internal Server Error |
Unexpected server error |
| 502 |
Bad Gateway |
External service error |
| 503 |
Service Unavailable |
Service temporarily unavailable |
| 504 |
Gateway Timeout |
External service timeout |
Error Categories#
Authentication Errors#
Authentication errors occur when verifying user identity.
| Code |
Status |
Description |
Resolution |
auth.invalid_credentials |
401 |
Email or password incorrect |
Verify credentials and retry |
auth.login_failed |
401 |
Login attempt failed |
Check credentials |
auth.unauthorized |
401 |
Not authenticated |
Provide valid token |
auth.authentication_failed |
401 |
Authentication failed |
Re-authenticate |
auth.token_expired |
401 |
JWT token has expired |
Refresh token |
auth.session_expired |
401 |
Session no longer valid |
Log in again |
auth.invalid_token |
401 |
Token is invalid or malformed |
Get new token |
auth.oauth_error |
400 |
OAuth provider error |
Retry OAuth flow |
auth.oauth_missing_params |
400 |
Missing OAuth parameters |
Include required params |
Authorization Errors#
Authorization errors occur when checking permissions.
| Code |
Status |
Description |
Resolution |
auth.forbidden |
403 |
Access denied |
Check permissions |
auth.access_denied |
403 |
Resource access denied |
Request access |
auth.insufficient_permissions |
403 |
Missing required permission |
Contact admin |
Validation Errors#
Validation errors occur when input data is invalid.
| Code |
Status |
Description |
Resolution |
validation.missing_field |
400 |
Required field is missing |
Provide required field |
validation.invalid_format |
400 |
Field format is incorrect |
Fix format |
validation.required_field |
400 |
Field is required |
Include field |
validation.multiple_field_errors |
400 |
Multiple validation errors |
See errors object |
validation.weak_password |
400 |
Password too weak |
Use stronger password |
validation.password_requirements |
400 |
Password doesn't meet requirements |
See requirements |
Validation Error Example:
json
{
"error": {
"code": "validation.multiple_field_errors",
"status": 400,
"title": "Validation Error",
"errors": {
"email": {
"message": "Invalid email format",
"code": "invalid_format"
},
"password": {
"message": "Password must be at least 8 characters",
"code": "min_length"
}
}
}
}
Rate Limiting Errors#
Rate limit errors occur when request quotas are exceeded.
| Code |
Status |
Retry After |
Description |
rate_limit_exceeded |
429 |
60s |
Request limit exceeded |
rate_limit.exceeded |
429 |
60s |
API rate limit hit |
quota_exceeded |
429 |
varies |
Usage quota exceeded |
Rate Limit Headers:
http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200
Service Errors#
Service errors occur when internal systems fail.
| Code |
Status |
Severity |
Resolution |
service.unavailable |
503 |
high |
Retry after delay |
service_timeout |
503 |
high |
Retry request |
service_connection_failed |
503 |
high |
Retry request |
circuit_breaker_open |
503 |
high |
Wait and retry |
service_degraded |
503 |
high |
Use fallback |
AI Service Errors#
Errors from AI/LLM processing.
| Code |
Status |
Description |
Resolution |
ai.completion_failed |
502 |
AI processing failed |
Retry request |
ai.model_unavailable |
502 |
Model not available |
Try different model |
ai.provider_error |
502 |
Provider returned error |
Retry or use fallback |
ai.context_window_exceeded |
400 |
Input too long |
Reduce message length |
ai.token_limit_exceeded |
400 |
Token limit reached |
Reduce input size |
Content Errors#
Errors related to content access and management.
| Code |
Status |
Description |
Resolution |
content.not_found |
404 |
Content does not exist |
Check content ID |
content.access_denied |
403 |
Cannot access content |
Check permissions |
Errors related to media upload and processing.
| Code |
Status |
Description |
Resolution |
media.upload_failed |
422 |
Upload failed |
Retry upload |
media.processing_failed |
422 |
Processing failed |
Check file format |
media.format_unsupported |
422 |
Unsupported format |
Use supported format |
Supported Formats:
- Audio: MP3, WAV, FLAC, M4A, OGG
- Video: MP4, MOV, WebM
- Image: JPEG, PNG, GIF, WebP
- Documents: PDF, DOCX, TXT, MD
Database Errors#
Internal database errors.
| Code |
Status |
Description |
Resolution |
database.connection_failed |
500 |
Database connection failed |
Retry request |
database.query_timeout |
500 |
Query timed out |
Retry request |
database.constraint_violation |
500 |
Constraint violated |
Check data |
Daily Content Service Errors#
Meditation Errors#
| Code |
Status |
Description |
daily_content.meditation_not_found |
404 |
Meditation not found |
daily_content.schedule_not_found |
404 |
Schedule not found |
daily_content.preferences_not_found |
404 |
Preferences not found |
daily_content.invalid_date |
400 |
Invalid date format |
daily_content.invalid_timezone |
400 |
Invalid timezone |
daily_content.queue_generation_failed |
500 |
Queue generation failed |
daily_content.streak_calculation_error |
500 |
Streak calculation failed |
Quote Errors#
| Code |
Status |
Description |
daily_content.quote_not_found |
404 |
Quote not found |
daily_content.no_quotes_available |
503 |
No quotes available |
daily_content.quote_already_favorited |
409 |
Already favorited |
daily_content.quote_not_favorited |
404 |
Quote not in favorites |
daily_content.quote_share_failed |
500 |
Share operation failed |
Moments Errors#
| Code |
Status |
Description |
daily_content.moment_not_found |
404 |
Moment not found |
daily_content.no_moments_available |
503 |
No moments available |
daily_content.invalid_moment_context |
400 |
Invalid context |
daily_content.invalid_moment_duration |
400 |
Invalid duration |
Reflection Errors#
| Code |
Status |
Description |
daily_content.reflection_not_found |
404 |
Reflection not found |
daily_content.invalid_mood_rating |
400 |
Invalid mood rating (1-5) |
daily_content.invalid_energy_level |
400 |
Invalid energy level (1-5) |
daily_content.prompt_not_found |
404 |
Prompt not found |
daily_content.insight_not_found |
404 |
Insight not found |
daily_content.summary_not_available |
503 |
Summary not available |
Course Errors#
| Code |
Status |
Description |
daily_content.course_not_found |
404 |
Course not found |
daily_content.day_not_found |
404 |
Course day not found |
daily_content.day_locked |
403 |
Course day is locked |
daily_content.not_enrolled |
403 |
Not enrolled in course |
daily_content.already_enrolled |
409 |
Already enrolled |
daily_content.enrollment_failed |
500 |
Enrollment failed |
daily_content.progress_update_failed |
500 |
Progress update failed |
daily_content.certificate_not_available |
404 |
Certificate not ready |
daily_content.course_not_complete |
409 |
Course not completed |
Sleep Content Errors#
| Code |
Status |
Description |
sleep.content_not_found |
404 |
Sleep content not found |
sleep.session_not_found |
404 |
Sleep session not found |
sleep.invalid_timer_duration |
400 |
Invalid timer duration |
sleep.no_suggestions_available |
503 |
No suggestions available |
sleep.session_already_ended |
409 |
Session already ended |
Sleep Tracking Errors#
| Code |
Status |
Description |
sleep_tracking.profile_not_found |
404 |
Sleep profile not found |
sleep_tracking.invalid_date_range |
400 |
Invalid date range |
sleep_tracking.insufficient_data |
400 |
Not enough data |
sleep_tracking.biometric_sync_failed |
503 |
Biometric sync failed |
sleep_tracking.no_recommendations |
503 |
No recommendations available |
Kids Meditation Errors#
| Code |
Status |
Description |
kids.child_profile_not_found |
404 |
Child profile not found |
kids.content_not_found |
404 |
Kids content not found |
kids.content_not_age_appropriate |
403 |
Content not appropriate for age |
kids.parental_consent_required |
403 |
Parental consent needed |
kids.daily_limit_exceeded |
429 |
Daily time limit reached |
kids.content_blocked_by_parent |
403 |
Content blocked by parent |
kids.session_not_found |
404 |
Session not found |
kids.profile_limit_reached |
400 |
Max profiles reached |
kids.invalid_age |
400 |
Invalid age value |
Family Meditation Errors#
| Code |
Status |
Description |
family.not_found |
404 |
Family not found |
family.not_owner |
403 |
Not family owner |
family.not_member |
403 |
Not family member |
family.child_not_in_family |
403 |
Child not in family |
family.session_not_found |
404 |
Session not found |
family.session_already_ended |
409 |
Session already ended |
family.challenge_not_found |
404 |
Challenge not found |
family.already_enrolled_in_challenge |
409 |
Already enrolled |
family.challenge_expired |
409 |
Challenge has expired |
family.content_not_found |
404 |
Content not found |
Forum Errors#
| Code |
Status |
Description |
forum.thread_not_found |
404 |
Thread not found |
forum.reply_not_found |
404 |
Reply not found |
forum.category_not_found |
404 |
Category not found |
forum.user_not_found |
404 |
User not found |
forum.permission_denied |
403 |
Permission denied |
forum.thread_locked |
403 |
Thread is locked |
forum.thread_closed |
403 |
Thread is closed |
forum.user_banned |
403 |
User is banned |
forum.user_muted |
403 |
User is muted |
forum.content_flagged |
403 |
Content was flagged |
forum.duplicate_reaction |
409 |
Already reacted |
forum.reaction_not_found |
404 |
Reaction not found |
forum.subscription_exists |
409 |
Already subscribed |
forum.subscription_not_found |
404 |
Subscription not found |
forum.flag_not_found |
404 |
Flag not found |
forum.invalid_parent_reply |
400 |
Invalid parent reply |
forum.max_nesting_depth |
400 |
Max reply depth reached |
forum.rate_limit_exceeded |
429 |
Post rate limit hit |
forum.content_too_short |
400 |
Content too short |
forum.content_too_long |
400 |
Content too long |
Profile Errors#
| Code |
Status |
Description |
community.profile_not_found |
404 |
Profile not found |
community.profile_private |
403 |
Profile is private |
community.invalid_visibility |
400 |
Invalid visibility setting |
Follow Errors#
| Code |
Status |
Description |
community.cannot_follow_self |
400 |
Cannot follow yourself |
community.already_following |
409 |
Already following |
community.not_following |
404 |
Not following user |
community.follow_not_allowed |
403 |
Follow not allowed |
community.user_blocked |
403 |
User is blocked |
Friend Errors#
| Code |
Status |
Description |
community.cannot_friend_self |
400 |
Cannot friend yourself |
community.already_friends |
409 |
Already friends |
community.friend_request_exists |
409 |
Request already sent |
community.friend_request_not_found |
404 |
Request not found |
community.friend_request_expired |
410 |
Request has expired |
community.not_friends |
403 |
Not friends |
community.friendship_not_found |
404 |
Friendship not found |
Sharing Errors#
| Code |
Status |
Description |
sharing.content_not_found |
404 |
Content not found |
sharing.content_not_shareable |
403 |
Content cannot be shared |
sharing.share_not_found |
404 |
Share not found |
sharing.not_owner |
403 |
Not content owner |
sharing.sharing_disabled |
403 |
Sharing is disabled |
sharing.visibility_restricted |
403 |
Visibility restricted |
sharing.password_required |
401 |
Password required |
sharing.password_incorrect |
401 |
Incorrect password |
sharing.share_expired |
410 |
Share has expired |
sharing.share_revoked |
410 |
Share was revoked |
sharing.daily_limit_exceeded |
429 |
Daily share limit hit |
sharing.invite_not_found |
404 |
Invite not found |
sharing.invite_expired |
410 |
Invite has expired |
Playlist Errors#
| Code |
Status |
Description |
playlist.not_found |
404 |
Playlist not found |
playlist.title_required |
400 |
Title is required |
playlist.not_owner |
403 |
Not playlist owner |
playlist.access_denied |
403 |
Access denied |
playlist.max_items_reached |
400 |
Max items reached |
playlist.duplicate_item |
409 |
Item already exists |
playlist.item_not_found |
404 |
Item not found |
playlist.item_order_invalid |
400 |
Invalid item order |
playlist.folder_not_found |
404 |
Folder not found |
playlist.folder_circular_reference |
400 |
Circular reference |
playlist.folder_max_depth_exceeded |
400 |
Max folder depth |
playlist.collaborator_not_found |
404 |
Collaborator not found |
playlist.collaborator_already_exists |
409 |
Already collaborating |
Conversation/Dialogue Errors#
| Code |
Status |
Description |
conversation.not_found |
404 |
Conversation not found |
conversation.chapter_not_found |
404 |
Chapter not found |
conversation.highlight_not_found |
404 |
Highlight not found |
conversation.transcript_not_found |
404 |
Transcript not found |
conversation.series_not_found |
404 |
Series not found |
conversation.speaker_not_found |
404 |
Speaker not found |
conversation.bookmark_not_found |
404 |
Bookmark not found |
conversation.progress_not_found |
404 |
Progress not found |
conversation.invalid_duration |
400 |
Invalid duration |
conversation.invalid_topic |
400 |
Invalid topic |
conversation.invalid_format |
400 |
Invalid format |
conversation.invalid_position |
400 |
Invalid position |
conversation.invalid_time_range |
400 |
Invalid time range |
conversation.access_denied |
403 |
Access denied |
conversation.premium_content |
403 |
Premium subscription required |
Podcast Errors#
| Code |
Status |
Description |
podcast.feed_not_found |
404 |
Podcast feed not found |
podcast.episode_not_found |
404 |
Episode not found |
podcast.subscription_not_found |
404 |
Subscription not found |
podcast.progress_not_found |
404 |
Progress not found |
podcast.invalid_audio_url |
400 |
Invalid audio URL |
podcast.invalid_image_url |
400 |
Invalid image URL |
podcast.invalid_duration |
400 |
Invalid duration |
podcast.invalid_category |
400 |
Invalid category |
podcast.invalid_episode_type |
400 |
Invalid episode type |
podcast.already_subscribed |
409 |
Already subscribed |
podcast.episode_already_exists |
409 |
Episode exists |
podcast.max_episodes_reached |
400 |
Max episodes reached |
podcast.max_subscriptions_reached |
400 |
Max subscriptions reached |
AI Generation Errors#
| Code |
Status |
Description |
ai_gen.generation_failed |
500 |
Generation failed |
ai_gen.generation_timeout |
504 |
Generation timed out |
ai_gen.generation_cancelled |
409 |
Generation cancelled |
ai_gen.invalid_speaker_count |
400 |
Invalid speaker count |
ai_gen.invalid_duration |
400 |
Invalid duration |
ai_gen.invalid_topic |
400 |
Invalid topic |
ai_gen.invalid_persona |
400 |
Invalid persona |
ai_gen.incompatible_speakers |
400 |
Speakers incompatible |
ai_gen.question_too_short |
400 |
Question too short |
ai_gen.question_too_long |
400 |
Question too long |
ai_gen.question_inappropriate |
400 |
Question inappropriate |
ai_gen.question_not_found |
404 |
Question not found |
ai_gen.question_already_answered |
409 |
Already answered |
Analytics Errors#
| Code |
Status |
Description |
analytics.insufficient_data |
400 |
Not enough data |
analytics.period_too_long |
400 |
Period too long |
analytics.invalid_period |
400 |
Invalid period |
analytics.goal_not_found |
404 |
Goal not found |
analytics.achievement_not_found |
404 |
Achievement not found |
analytics.year_not_available |
404 |
Year not available |
analytics.dashboard_generation_failed |
500 |
Dashboard failed |
analytics.summary_generation_failed |
500 |
Summary failed |
analytics.year_review_failed |
500 |
Year review failed |
analytics.insight_generation_failed |
500 |
Insights failed |
Moderation Errors#
| Code |
Status |
Description |
moderation.content_blocked |
403 |
Content violates policy |
moderation.policy_violation |
403 |
Policy violation detected |
moderation.blocked_term |
403 |
Blocked term used |
Knowledge Base Errors#
| Code |
Status |
Description |
knowledge.document_not_found |
404 |
Document not found |
knowledge.search_failed |
500 |
Search failed |
knowledge.embedding_error |
500 |
Embedding failed |
Network Errors#
| Code |
Status |
Description |
network_error |
502 |
Network error |
connection_timeout |
502 |
Connection timed out |
dns_resolution_failed |
502 |
DNS resolution failed |
Business Logic Errors#
| Code |
Status |
Description |
business.rule_violation |
409 |
Business rule violated |
business.invalid_state |
409 |
Invalid state transition |
business.conflict |
409 |
Resource conflict |
External Service Errors#
| Code |
Status |
Description |
external.api_error |
502 |
External API error |
external.quota_exceeded |
503 |
External quota exceeded |
external.service_down |
503 |
External service down |
Error Severity Levels#
| Level |
Description |
Action |
low |
Minor issue, operation can continue |
Log and continue |
medium |
Degraded operation |
Alert and monitor |
high |
Critical, use fallback |
Immediate attention |
critical |
System failure |
Emergency response |
Recovery Strategies#
| Error Type |
Strategy |
Fallback |
auth.token_expired |
Refresh token |
Cached auth |
auth.session_expired |
Re-authenticate |
Guest mode |
db.connection_failed |
Reconnect |
Cache only |
service.unavailable |
Circuit breaker |
Alternative service |
network.timeout |
Retry request |
Cached response |
rate_limit.exceeded |
Backoff retry |
Queue request |
content.not_found |
Search alternative |
Default content |
SDK Error Handling#
TypeScript/JavaScript#
typescript
import { LilithClient, LilithError } from '@lilith/sdk';
try {
const response = await client.chat.send({ message: 'Hello' });
} catch (error) {
if (error instanceof LilithError) {
switch (error.code) {
case 'auth.token_expired':
await client.auth.refresh();
// Retry request
break;
case 'rate_limit.exceeded':
await sleep(error.retryAfter * 1000);
// Retry request
break;
case 'ai.context_window_exceeded':
// Reduce message length
break;
default:
console.error(`Error: ${error.message}`);
}
}
}
Questions?#
- Technical Support: api-support@lilith.app
- Documentation Issues:
GitHub Issues