Error Codes Reference
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Complete reference of all error codes returned by the Freddy API. All errors follow a consistent format with machine-readable codes and user-friendly messages.

Error Response Structure

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "User-friendly message",
    "system_message": "Technical message",
    "type": "error_type",
    "status": 400,
    "details": {},
    "trace_id": "uuid",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Authentication Errors (401)

Code	Message	Description
`INVALID_CREDENTIALS`	Invalid email, username, or password	Wrong login credentials
`TOKEN_EXPIRED`	Your session has expired	JWT token expired
`TOKEN_INVALID`	Your session is invalid	Malformed or invalid token
`TOKEN_MISSING_SUBJECT`	Your session is invalid	Token missing subject claim
`AUTHENTICATION_REQUIRED`	Please sign in to continue	Missing authentication
`INVALID_API_KEY`	Your API key is invalid	Invalid API key format or value
`API_KEY_EXPIRED`	Your API key has expired	API key past expiration date
`API_KEY_DEACTIVATED`	Your API key has been deactivated	API key manually deactivated
`API_KEY_PAUSED`	Your API key is paused	API key temporarily paused

Authorization Errors (403)

Code	Message	Description
`INSUFFICIENT_PERMISSIONS`	You don't have permission to perform this action	Lacks required permissions
`ORGANIZATION_ACCESS_DENIED`	You don't have access to this organization	Not a member of organization
`DOMAIN_NOT_REGISTERED`	Your email domain is not registered	Email domain not allowed
`REGISTRATION_RESTRICTED`	Registration is restricted	Registration not allowed
`OPERATION_NOT_ALLOWED`	This operation is not allowed	Operation forbidden
`NO_ORGANIZATION_MEMBERSHIP`	You are not a member of any organization	No organization membership
`AMBIGUOUS_ORGANIZATION`	Please specify which organization to use	Multiple organizations, need to specify
`ACCESS_DENIED`	You don't have permission to access this rule	General access denied
`CANNOT_REMOVE_LAST_OWNER`	Cannot remove the last owner of a rule	Must have at least one owner
`CANNOT_DELETE_OWNER`	The organization owner cannot be deleted	Owner protection
`CANNOT_MODIFY_OWNER`	The organization owner's role or status cannot be modified	Owner protection
`SCOPE_RESTRICTED`	Global scope rules can only be created by system administrators	Scope restriction

Validation Errors (422)

Code	Message	Description
`VALIDATION_ERROR`	Please check your input and try again	General validation failure
`INVALID_EMAIL_FORMAT`	Please enter a valid email address	Email format invalid
`INVALID_PASSWORD_FORMAT`	Password does not meet requirements	Password validation failed
`MISSING_REQUIRED_FIELD`	Please fill out all required fields	Required field missing
`INVALID_FIELD_VALUE`	One or more fields contain invalid values	Field value invalid
`INVALID_USERNAME_FORMAT`	Username contains invalid characters	Username format invalid
`INVALID_INPUT`	Invalid input provided	General input validation
`INVALID_MODEL_KEY`	The model you specified is not available	Model key invalid
`INVALID_LIMIT_VALUE`	Invalid limit value	Limit value out of range
`INVALID_CATEGORY`	Invalid rule category	Category not recognized
`INVALID_RULE_TYPE`	Invalid rule type	Rule type not recognized
`INVALID_SCOPE`	Invalid rule scope	Scope not recognized
`INVALID_APPLY_MODE`	Invalid apply mode	Apply mode not recognized
`INVALID_ENTITY_TYPE`	Invalid entity type	Entity type not recognized
`INVALID_ACCESS_LEVEL`	Invalid access level	Access level not recognized
`INVALID_SORT_FIELD`	The specified sort field is not valid	Sort field invalid
`INVALID_PAGINATION_PARAMS`	Invalid pagination parameters	Pagination params invalid
`INVALID_QUERY_PARAMETERS`	Invalid query parameters	Query params invalid
`INVALID_REQUEST_BODY`	Invalid request body	Request body malformed
`INVALID_ID_FORMAT`	Invalid ID format	ID format incorrect

Resource Errors (404)

Code	Message	Description
`USER_NOT_FOUND`	We couldn't find an account with that information	User doesn't exist
`ORGANIZATION_NOT_FOUND`	Organization not found	Organization doesn't exist
`RESOURCE_NOT_FOUND`	The requested resource could not be found	Generic resource not found
`THREAD_NOT_FOUND`	Thread not found	Thread doesn't exist
`MESSAGE_NOT_FOUND`	Message not found	Message doesn't exist
`RULE_NOT_FOUND`	The requested rule could not be found	Rule doesn't exist
`MEMBER_NOT_FOUND`	The specified member could not be found	Member doesn't exist
`ROLE_NOT_FOUND`	The specified role could not be found	Role doesn't exist
`STATUS_NOT_FOUND`	The specified status could not be found	Status doesn't exist
`INVITATION_NOT_FOUND`	The invitation could not be found	Invitation doesn't exist
`ATTACHMENT_NOT_FOUND`	The requested attachment could not be found	Attachment doesn't exist
`ACCESS_RIGHT_NOT_FOUND`	The requested access right could not be found	Access right doesn't exist
`ICON_NOT_FOUND`	The requested icon could not be found	Icon doesn't exist
`API_KEY_NOT_FOUND`	API key not found	API key doesn't exist
`VECTOR_STORE_NOT_FOUND`	Vector store not found	Vector store doesn't exist
`VECTOR_STORE_FILE_NOT_FOUND`	Vector store file not found	File not found in vector store
`FILE_NOT_FOUND`	File not found	File doesn't exist
`JOB_NOT_FOUND`	Job not found	Scraping job doesn't exist
`BATCH_NOT_FOUND`	Batch not found	Batch doesn't exist
`VERIFICATION_NOT_FOUND`	Verification not found	Verification record doesn't exist

Conflict Errors (409)

Code	Message	Description
`USER_ALREADY_EXISTS`	An account with this email already exists	Email already registered
`USERNAME_TAKEN`	This username is already taken	Username not available
`RESOURCE_ALREADY_EXISTS`	This resource already exists	Generic conflict
`EMAIL_ALREADY_REGISTERED`	Email already registered	Email in use
`RULE_NAME_DUPLICATE`	A rule with this name already exists in your organization	Rule name must be unique
`ATTACHMENT_ALREADY_EXISTS`	This entity is already attached to this rule	Attachment exists
`ACCESS_RIGHT_ALREADY_EXISTS`	This user already has access to this rule	Access right exists
`INVITATION_ALREADY_ACCEPTED`	This invitation has already been accepted	Invitation used
`MEMBER_ALREADY_DELETED`	This member has already been deleted	Member deleted
`VECTOR_STORE_FILE_ALREADY_EXISTS`	File already exists in vector store	Duplicate file
`CONFLICT`	This action conflicts with existing data	Generic conflict

Rate Limit Errors (429)

Code	Message	Description
`RATE_LIMIT_EXCEEDED`	Too many requests. Please wait a moment and try again	General rate limit
`TOO_MANY_LOGIN_ATTEMPTS`	Too many login attempts. Please try again later	Login rate limit
`TOO_MANY_VERIFICATION_ATTEMPTS`	Too many verification attempts. Please try again later	Verification rate limit
`SPENDING_LIMIT_EXCEEDED`	Your monthly spending limit has been reached	Spending limit hit

Server Errors (500)

Code	Message	Description
`INTERNAL_ERROR`	Something went wrong. Please try again later	Unexpected server error
`DATABASE_ERROR`	Service temporarily unavailable. Please try again later	Database operation failed
`DATABASE_CONNECTION_ERROR`	Service temporarily unavailable. Please try again later	Database connection failed
`EMAIL_SEND_FAILED`	Failed to send email. Please try again later	Email service failure
`CONFIGURATION_ERROR`	Service configuration error. Please contact support	Configuration issue
`STORAGE_SERVICE_UNAVAILABLE`	Image upload service is temporarily unavailable	Storage service down
`STORAGE_UPLOAD_FAILED`	Failed to upload image. Please try again later	Upload failed
`STORAGE_ERROR`	Storage error occurred	Storage operation failed
`PROVIDER_UNAVAILABLE`	External service is temporarily unavailable	Provider down
`PROVIDER_TIMEOUT`	Request timed out. Please try again	Provider timeout
`PROVIDER_ERROR`	External service error. Please try again later	Provider error
`PROVIDER_NOT_CONFIGURED`	Provider not configured	Provider setup missing

Rule Management Errors

Code	Status	Message
`RULE_CONTENT_TOO_LARGE`	422	Rule content exceeds the maximum allowed size of 50,000 characters
`RULE_CONTENT_EMPTY`	422	Rule content cannot be empty
`RULE_HAS_ATTACHMENTS`	409	This rule cannot be deleted because it is attached to one or more entities
`ATTACHMENT_INVALID_ENTITY`	422	The specified entity is invalid or does not exist
`ATTACHMENT_PRIORITY_INVALID`	422	Priority must be between 1 and 100
`ATTACHMENT_CHAR_LIMIT_INVALID`	422	Character limit must be between 100 and 50,000

File & Vector Store Errors

Code	Status	Message
`FILE_TOO_LARGE`	422	File exceeds maximum size limit
`FILE_SIZE_MISMATCH`	422	File size doesn't match expected size
`INVALID_FILE_TYPE`	422	File type not supported
`INVALID_FILE_FORMAT`	422	File format invalid
`FILE_PARSING_ERROR`	500	Failed to parse file
`FILE_NOT_PROCESSED`	400	File has not been processed yet
`FILE_CONTEXT_RETRIEVAL_FAILED`	500	Failed to retrieve context from files
`TOO_MANY_FILES`	422	Too many files attached (max 10)
`CORRUPTED_DOCUMENT`	422	Document is corrupted or unreadable
`FILE_PROCESSING_FAILED`	500	File processing failed
`VECTOR_STORE_ACCESS_DENIED`	403	Access denied to vector store
`VECTOR_STORE_INVALID_ACCESS_MODE`	422	Invalid access mode
`INVALID_STATUS`	422	Invalid status value
`INVALID_STATUS_TRANSITION`	422	Invalid status transition

Verification Errors

Code	Status	Message
`VERIFICATION_CODE_INVALID`	422	Invalid verification code. Please try again
`VERIFICATION_CODE_EXPIRED`	422	Verification code has expired. Please request a new one
`VERIFICATION_ALREADY_USED`	409	This verification code has already been used
`VERIFICATION_ATTEMPTS_EXCEEDED`	429	Too many verification attempts. Please request a new code
`INVALID_VERIFICATION_TYPE`	422	This verification code cannot be used for this purpose

Crew Management Errors

Code	Status	Message
`MEMBER_NOT_DELETED`	400	This member is not deleted and cannot be restored
`EXPORT_LIMIT_EXCEEDED`	422	Export exceeds the maximum limit
`BULK_OPERATION_LIMIT_EXCEEDED`	422	Bulk operation exceeds the maximum limit

Image & Icon Errors

Code	Status	Message
`ICON_UPLOAD_FAILED`	500	Failed to upload icon
`ICON_FILE_NOT_FOUND`	404	Icon file not found
`ICON_INVALID_FORMAT`	422	Invalid icon format (must be SVG, PNG, or JPG)
`ICON_FILE_TOO_LARGE`	422	Icon file is too large (max 5MB)
`ICON_INVALID_SVG`	422	Invalid SVG file (contains unsafe content)
`IMAGE_DOWNLOAD_FAILED`	500	Failed to download image from URL
`UNSUPPORTED_OPERATION`	422	Operation not supported
`INVALID_IMAGE_FORMAT`	422	Invalid image format
`IMAGE_TOO_LARGE`	422	Image exceeds maximum size

Web Scraping Errors

Code	Status	Message
`SCRAPING_FAILED`	500	Web scraping operation failed
`BATCH_SCRAPING_FAILED`	500	Batch scraping failed
`INVALID_URL`	422	Invalid URL provided
`TIMEOUT_EXCEEDED`	500	Operation timed out
`SITE_BLOCKED`	403	Site blocked scraping
`JOB_LIST_FAILED`	500	Failed to list jobs
`JOB_CANCELLATION_FAILED`	500	Failed to cancel job

Best Practices

Error Handling

Always check the success field - It's false for all errors
Use the code field - Machine-readable, consistent across versions
Display the message field - User-friendly, safe for UI
Log the system_message - Technical details for debugging
Include trace_id in support requests - Helps track issues
Check details for context - Additional error-specific information

Retry Logic

401/403: Don't retry, fix authentication/authorization
404: Don't retry, resource doesn't exist
422: Don't retry, fix validation errors
429: Retry after details.retry_after seconds
500/502/503: Retry with exponential backoff
504: Retry with longer timeout

Example Error Handler

def handle_api_error(response):
    if response.status_code >= 400:
        error_data = response.json()
        error = error_data.get("error", {})
        
        code = error.get("code")
        message = error.get("message")
        trace_id = error.get("trace_id")
        
        # Log for debugging
        print(f"Error {code}: {error.get('system_message')}")
        print(f"Trace ID: {trace_id}")
        
        # Display to user
        print(f"User message: {message}")
        
        # Handle specific errors
        if code == "TOKEN_EXPIRED":
            # Refresh token
            pass
        elif code == "RATE_LIMIT_EXCEEDED":
            # Wait and retry
            retry_after = error.get("details", {}).get("retry_after", 60)
            time.sleep(retry_after)
        
        return error

Error Codes ReferenceCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Error Response Structure

Authentication Errors (401)

Authorization Errors (403)

Validation Errors (422)

Resource Errors (404)

Conflict Errors (409)

Rate Limit Errors (429)

Server Errors (500)

Rule Management Errors

File & Vector Store Errors

Verification Errors

Crew Management Errors

Image & Icon Errors

Web Scraping Errors

Best Practices

Error Handling

Retry Logic

Example Error Handler

Related Resources

Was this helpful?

Error Codes Reference
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude