# Error Codes Reference

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


```json
{
  "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

1. **Always check the `success` field** - It's `false` for all errors
2. **Use the `code` field** - Machine-readable, consistent across versions
3. **Display the `message` field** - User-friendly, safe for UI
4. **Log the `system_message`** - Technical details for debugging
5. **Include `trace_id` in support requests** - Helps track issues
6. **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


```python
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
```

## Related Resources

- [Error Handling Guide](/docs/documentation/error-handling)
- [Authentication](/docs/api-reference/authentication)
- [Rate Limiting](/docs/documentation#rate-limiting)