Eve library

Error Codes Reference

Guide

Revision 1

On this page

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)

Error Response Headers#

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

Media Errors#

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

Community Errors#

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