Last updated 2 months ago
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.
{ "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_CREDENTIALSInvalid email, username, or password Wrong login credentials TOKEN_EXPIREDYour session has expired JWT token expired TOKEN_INVALIDYour session is invalid Malformed or invalid token TOKEN_MISSING_SUBJECTYour session is invalid Token missing subject claim AUTHENTICATION_REQUIREDPlease sign in to continue Missing authentication INVALID_API_KEYYour API key is invalid Invalid API key format or value API_KEY_EXPIREDYour API key has expired API key past expiration date API_KEY_DEACTIVATEDYour API key has been deactivated API key manually deactivated API_KEY_PAUSEDYour API key is paused API key temporarily paused
Authorization Errors (403) Code Message Description INSUFFICIENT_PERMISSIONSYou don't have permission to perform this action Lacks required permissions ORGANIZATION_ACCESS_DENIEDYou don't have access to this organization Not a member of organization DOMAIN_NOT_REGISTEREDYour email domain is not registered Email domain not allowed REGISTRATION_RESTRICTEDRegistration is restricted Registration not allowed OPERATION_NOT_ALLOWEDThis operation is not allowed Operation forbidden NO_ORGANIZATION_MEMBERSHIPYou are not a member of any organization No organization membership AMBIGUOUS_ORGANIZATIONPlease specify which organization to use Multiple organizations, need to specify ACCESS_DENIEDYou don't have permission to access this rule General access denied CANNOT_REMOVE_LAST_OWNERCannot remove the last owner of a rule Must have at least one owner CANNOT_DELETE_OWNERThe organization owner cannot be deleted Owner protection CANNOT_MODIFY_OWNERThe organization owner's role or status cannot be modified Owner protection SCOPE_RESTRICTEDGlobal scope rules can only be created by system administrators Scope restriction
Code Message Description VALIDATION_ERRORPlease check your input and try again General validation failure INVALID_EMAIL_FORMATPlease enter a valid email address Email format invalid INVALID_PASSWORD_FORMATPassword does not meet requirements Password validation failed MISSING_REQUIRED_FIELDPlease fill out all required fields Required field missing INVALID_FIELD_VALUEOne or more fields contain invalid values Field value invalid INVALID_USERNAME_FORMATUsername contains invalid characters Username format invalid INVALID_INPUTInvalid input provided General input validation INVALID_MODEL_KEYThe model you specified is not available Model key invalid INVALID_LIMIT_VALUEInvalid limit value Limit value out of range INVALID_CATEGORYInvalid rule category Category not recognized INVALID_RULE_TYPEInvalid rule type Rule type not recognized INVALID_SCOPEInvalid rule scope Scope not recognized INVALID_APPLY_MODEInvalid apply mode Apply mode not recognized INVALID_ENTITY_TYPEInvalid entity type Entity type not recognized INVALID_ACCESS_LEVELInvalid access level Access level not recognized INVALID_SORT_FIELDThe specified sort field is not valid Sort field invalid INVALID_PAGINATION_PARAMSInvalid pagination parameters Pagination params invalid INVALID_QUERY_PARAMETERSInvalid query parameters Query params invalid INVALID_REQUEST_BODYInvalid request body Request body malformed INVALID_ID_FORMATInvalid ID format ID format incorrect
Code Message Description USER_NOT_FOUNDWe couldn't find an account with that information User doesn't exist ORGANIZATION_NOT_FOUNDOrganization not found Organization doesn't exist RESOURCE_NOT_FOUNDThe requested resource could not be found Generic resource not found THREAD_NOT_FOUNDThread not found Thread doesn't exist MESSAGE_NOT_FOUNDMessage not found Message doesn't exist RULE_NOT_FOUNDThe requested rule could not be found Rule doesn't exist MEMBER_NOT_FOUNDThe specified member could not be found Member doesn't exist ROLE_NOT_FOUNDThe specified role could not be found Role doesn't exist STATUS_NOT_FOUNDThe specified status could not be found Status doesn't exist INVITATION_NOT_FOUNDThe invitation could not be found Invitation doesn't exist ATTACHMENT_NOT_FOUNDThe requested attachment could not be found Attachment doesn't exist ACCESS_RIGHT_NOT_FOUNDThe requested access right could not be found Access right doesn't exist ICON_NOT_FOUNDThe requested icon could not be found Icon doesn't exist API_KEY_NOT_FOUNDAPI key not found API key doesn't exist VECTOR_STORE_NOT_FOUNDVector store not found Vector store doesn't exist VECTOR_STORE_FILE_NOT_FOUNDVector store file not found File not found in vector store FILE_NOT_FOUNDFile not found File doesn't exist JOB_NOT_FOUNDJob not found Scraping job doesn't exist BATCH_NOT_FOUNDBatch not found Batch doesn't exist VERIFICATION_NOT_FOUNDVerification not found Verification record doesn't exist
Code Message Description USER_ALREADY_EXISTSAn account with this email already exists Email already registered USERNAME_TAKENThis username is already taken Username not available RESOURCE_ALREADY_EXISTSThis resource already exists Generic conflict EMAIL_ALREADY_REGISTEREDEmail already registered Email in use RULE_NAME_DUPLICATEA rule with this name already exists in your organization Rule name must be unique ATTACHMENT_ALREADY_EXISTSThis entity is already attached to this rule Attachment exists ACCESS_RIGHT_ALREADY_EXISTSThis user already has access to this rule Access right exists INVITATION_ALREADY_ACCEPTEDThis invitation has already been accepted Invitation used MEMBER_ALREADY_DELETEDThis member has already been deleted Member deleted VECTOR_STORE_FILE_ALREADY_EXISTSFile already exists in vector store Duplicate file CONFLICTThis action conflicts with existing data Generic conflict
Code Message Description RATE_LIMIT_EXCEEDEDToo many requests. Please wait a moment and try again General rate limit TOO_MANY_LOGIN_ATTEMPTSToo many login attempts. Please try again later Login rate limit TOO_MANY_VERIFICATION_ATTEMPTSToo many verification attempts. Please try again later Verification rate limit SPENDING_LIMIT_EXCEEDEDYour monthly spending limit has been reached Spending limit hit
Code Message Description INTERNAL_ERRORSomething went wrong. Please try again later Unexpected server error DATABASE_ERRORService temporarily unavailable. Please try again later Database operation failed DATABASE_CONNECTION_ERRORService temporarily unavailable. Please try again later Database connection failed EMAIL_SEND_FAILEDFailed to send email. Please try again later Email service failure CONFIGURATION_ERRORService configuration error. Please contact support Configuration issue STORAGE_SERVICE_UNAVAILABLEImage upload service is temporarily unavailable Storage service down STORAGE_UPLOAD_FAILEDFailed to upload image. Please try again later Upload failed STORAGE_ERRORStorage error occurred Storage operation failed PROVIDER_UNAVAILABLEExternal service is temporarily unavailable Provider down PROVIDER_TIMEOUTRequest timed out. Please try again Provider timeout PROVIDER_ERRORExternal service error. Please try again later Provider error PROVIDER_NOT_CONFIGUREDProvider not configured Provider setup missing
Code Status Message RULE_CONTENT_TOO_LARGE422 Rule content exceeds the maximum allowed size of 50,000 characters RULE_CONTENT_EMPTY422 Rule content cannot be empty RULE_HAS_ATTACHMENTS409 This rule cannot be deleted because it is attached to one or more entities ATTACHMENT_INVALID_ENTITY422 The specified entity is invalid or does not exist ATTACHMENT_PRIORITY_INVALID422 Priority must be between 1 and 100 ATTACHMENT_CHAR_LIMIT_INVALID422 Character limit must be between 100 and 50,000
File & Vector Store Errors Code Status Message FILE_TOO_LARGE422 File exceeds maximum size limit FILE_SIZE_MISMATCH422 File size doesn't match expected size INVALID_FILE_TYPE422 File type not supported INVALID_FILE_FORMAT422 File format invalid FILE_PARSING_ERROR500 Failed to parse file FILE_NOT_PROCESSED400 File has not been processed yet FILE_CONTEXT_RETRIEVAL_FAILED500 Failed to retrieve context from files TOO_MANY_FILES422 Too many files attached (max 10) CORRUPTED_DOCUMENT422 Document is corrupted or unreadable FILE_PROCESSING_FAILED500 File processing failed VECTOR_STORE_ACCESS_DENIED403 Access denied to vector store VECTOR_STORE_INVALID_ACCESS_MODE422 Invalid access mode INVALID_STATUS422 Invalid status value INVALID_STATUS_TRANSITION422 Invalid status transition
Code Status Message VERIFICATION_CODE_INVALID422 Invalid verification code. Please try again VERIFICATION_CODE_EXPIRED422 Verification code has expired. Please request a new one VERIFICATION_ALREADY_USED409 This verification code has already been used VERIFICATION_ATTEMPTS_EXCEEDED429 Too many verification attempts. Please request a new code INVALID_VERIFICATION_TYPE422 This verification code cannot be used for this purpose
Code Status Message MEMBER_NOT_DELETED400 This member is not deleted and cannot be restored EXPORT_LIMIT_EXCEEDED422 Export exceeds the maximum limit BULK_OPERATION_LIMIT_EXCEEDED422 Bulk operation exceeds the maximum limit
Code Status Message ICON_UPLOAD_FAILED500 Failed to upload icon ICON_FILE_NOT_FOUND404 Icon file not found ICON_INVALID_FORMAT422 Invalid icon format (must be SVG, PNG, or JPG) ICON_FILE_TOO_LARGE422 Icon file is too large (max 5MB) ICON_INVALID_SVG422 Invalid SVG file (contains unsafe content) IMAGE_DOWNLOAD_FAILED500 Failed to download image from URL UNSUPPORTED_OPERATION422 Operation not supported INVALID_IMAGE_FORMAT422 Invalid image format IMAGE_TOO_LARGE422 Image exceeds maximum size
Code Status Message SCRAPING_FAILED500 Web scraping operation failed BATCH_SCRAPING_FAILED500 Batch scraping failed INVALID_URL422 Invalid URL provided TIMEOUT_EXCEEDED500 Operation timed out SITE_BLOCKED403 Site blocked scraping JOB_LIST_FAILED500 Failed to list jobs JOB_CANCELLATION_FAILED500 Failed to cancel job
Always check the success field - It's false for all errorsUse the code field - Machine-readable, consistent across versionsDisplay the message field - User-friendly, safe for UILog the system_message - Technical details for debuggingInclude trace_id in support requests - Helps track issuesCheck details for context - Additional error-specific information401/403 : Don't retry, fix authentication/authorization404 : Don't retry, resource doesn't exist422 : Don't retry, fix validation errors429 : Retry after details.retry_after seconds500/502/503 : Retry with exponential backoff504 : Retry with longer timeoutdef 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