# 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; the key's `paused_reason` says why |


## 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 |
| `ORGANIZATION_MEMBERSHIP_UNREADABLE` | We couldn't confirm your organization membership for this request | Memberships could not be read, so an organization-level permission could not be checked; retry or sign in again |
| `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 |
| `ROLE_NOT_INVITABLE` | You are not allowed to invite members into this role | The requested role is not on the inviter's invite allowlist |
| `MEMBERSHIP_EXPIRED` | Your access expired because the account wasn't used for a while | Guest access lapsed on the rolling inactivity clock. `details.can_self_extend` says whether the emailed reactivation link still works |
| `MEMBERSHIP_HARD_EXPIRED` | Your access reached its end date and has been suspended | Guest access lapsed at an absolute deadline. Never self-extendable — only an administrator can restore it |
| `EXTENSION_NOT_AVAILABLE` | This account can't be reactivated from here | A reactivation link was presented for a membership it may no longer restore — one carrying an absolute deadline, deactivated by an administrator, promoted out of Guest, or past its grace window |


## API key errors

| Code | HTTP | Meaning | Page |
|  --- | --- | --- | --- |
| `API_KEY_PERSON_REQUIRED` | 403 | This API key acts as the organization, not as a person, and this operation needs a person. | [errors/api-key-person-required.md](/docs/api-reference/errors/api-key-person-required) |
| `API_KEY_CONSENT_PENDING` | 403 | This API key is waiting for the person it acts as to accept. It works once they accept. | [errors/api-key-consent-pending.md](/docs/api-reference/errors/api-key-consent-pending) |
| `API_KEY_ACTING_USER_INACTIVE` | 403 | The person this API key acts as can no longer use it here. An admin can put another member behind it, convert it, or delete it. | [errors/api-key-acting-user-inactive.md](/docs/api-reference/errors/api-key-acting-user-inactive) |
| `API_KEY_ACTING_USER_NOT_MEMBER` | 422 | The person this API key acts as is not a member of that organization. | [errors/api-key-acting-user-not-member.md](/docs/api-reference/errors/api-key-acting-user-not-member) |
| `API_KEY_KIND_NOT_ALLOWED` | 403 / 422 | This API key's kind can't be used for this operation. | [errors/api-key-kind-not-allowed.md](/docs/api-reference/errors/api-key-kind-not-allowed) |
| `API_KEY_CONSENT_REQUEST_NOT_FOUND` | 404 | That consent request doesn't exist. | [errors/api-key-consent-request-not-found.md](/docs/api-reference/errors/api-key-consent-request-not-found) |
| `API_KEY_CONSENT_REQUEST_NOT_PENDING` | 409 | That consent request was already answered, cancelled or has expired. | [errors/api-key-consent-request-not-pending.md](/docs/api-reference/errors/api-key-consent-request-not-pending) |
| `API_KEY_CONSENT_ALREADY_PENDING` | 409 | This API key already has a consent request waiting for an answer. | [errors/api-key-consent-already-pending.md](/docs/api-reference/errors/api-key-consent-already-pending) |
| `API_KEY_OFFER_NOT_FOUND` | 404 | This API key suggestion was not found. | [errors/api-key-offer-not-found.md](/docs/api-reference/errors/api-key-offer-not-found) |
| `API_KEY_OFFER_NOT_OPEN` | 409 | This suggestion is no longer open. The key may have changed, or you already answered it. | [errors/api-key-offer-not-open.md](/docs/api-reference/errors/api-key-offer-not-open) |
| `API_KEY_ADMIN_OPTION_PASSKEY_REQUIRED` | 403 | Letting an API key use your admin powers needs a passkey confirmation. Add a passkey to your account first, then confirm with it. | [errors/api-key-admin-option-passkey-required.md](/docs/api-reference/errors/api-key-admin-option-passkey-required) |
| `API_KEY_IP_NOT_ALLOWED` | 403 | This API key is restricted to specific IP ranges and this request came from outside them. Call from an allowed network, or ask an admin to add your range. | [errors/api-key-ip-not-allowed.md](/docs/api-reference/errors/api-key-ip-not-allowed) |
| `API_KEY_RATE_LIMITED` | 429 | This API key has reached its per-minute request limit. Retry after the time in the Retry-After header, or ask an admin to raise the key's limit. | [errors/api-key-rate-limited.md](/docs/api-reference/errors/api-key-rate-limited) |
| `API_KEY_GRANT_REQUIRED` | 422 | Choose what this key may do: pick a preset or grant at least one area. | [errors/api-key-grant-required.md](/docs/api-reference/errors/api-key-grant-required) |
| `API_KEY_RESOURCE_FORBIDDEN` | 403 | This API key is not allowed to use this resource. An admin can add it to the key's selected resources. | [errors/api-key-resource-forbidden.md](/docs/api-reference/errors/api-key-resource-forbidden) |
| `API_KEY_SCOPE_FORBIDDEN` | 403 | This API key's scopes do not allow this operation. Use a key with the required scope, or remove the key's scope restriction. | [errors/api-key-scope-forbidden.md](/docs/api-reference/errors/api-key-scope-forbidden) |


## 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; `details.reason` is `weak` or `reused` |
| `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 |
| `CHECK_SOURCE_SPAN_NOT_FOUND` | That text is not part of this answer. Select text from the answer and try again. | The highlighted text sent to check source is not in that assistant answer |
| `ROLE_TYPE_MISMATCH` | This role cannot be used here because its type does not match the assignment | e.g. a department role sent to an invite allowlist |
| `EXTENSION_LINK_INVALID` | This reactivation link isn't valid | The guest-access token is not recognized |
| `EXTENSION_LINK_EXPIRED` | This reactivation link has expired | The token is past the organization's grace window |
| `EXTENSION_LINK_ALREADY_USED` | This reactivation link has already been used | Tokens are single-use; the first click almost certainly succeeded, so invite the user to sign in |


## 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 |
| `ROUTINE_CHAT_BUSY` | The routine's chat stayed busy with another run, so this run did not start. | A rolling routine's run waited too long for its chat; retryable, and timed and event runs retry automatically |


## 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 |


## Connector Scope Option Errors

Returned by [List a source's scope options](/assets/list-source-scope-options.496bebab0aaa6c307bc43ead77397df173881c656d362e708c405c1e42b0f5b9.8ad048d0.md), its [personal counterpart](/assets/list-personal-source-scope-options.bfbea64c6f70e4e2fe9d4521c5176ccfa4b491d9dac4e12b522fd8d89e11c940.027aef60.md), and [List scope options before saving](/assets/list-draft-scope-options.72471c697e1b6f0bd801b07aa2c45e3263be3e47e783cf7f3554cfeee13942e8.8ad048d0.md).

| Code | Status | Message |
|  --- | --- | --- |
| `CONNECTOR_SCOPE_OPTIONS_INVALID_REQUEST` | 422 | The options for this setting couldn't be listed with this request |
| `CONNECTOR_SCOPE_PARENT_NOT_FOUND` | 404 | This folder no longer exists. Reload the list from the top |
| `CONNECTOR_SOURCE_CONFIG_UNUSABLE` | 409 | The saved connection settings can't be used to list the options |
| `CONNECTOR_PROVIDER_RATE_LIMITED` | 429 | The provider is limiting requests right now. Please try again in a few seconds |
| `CONNECTOR_SCOPE_OPTIONS_UNAVAILABLE` | 501 | Picking from a list isn't available for this connector yet. Enter the values instead |
| `CONNECTOR_SCOPE_OPTIONS_PRESAVE_UNAVAILABLE` | 501 | The options can only be listed once the connector is saved. Save it first, then pick from the list |
| `CONNECTOR_SCOPE_OPTIONS_FAILED` | 502 | The provider couldn't list the options right now. Please try again later |


## Table and Collection Errors

Returned by the [Tables](/docs/api-reference/smoc/databases/list-tables) and [Collections](/docs/api-reference/smoc/collections/list-collections) endpoints. Codes marked "inside `issues`" never come back as an HTTP error; they describe one entry of an import, or one value of a conversion, that was not copied.

| Code | Status | Message |
|  --- | --- | --- |
| `COLLECTION_BATCH_DUPLICATE_KEY` | 422 | A batch can write each key only once. |
| `COLLECTION_BATCH_TOO_LARGE` | 413 | The batch is larger than 10 MB. |
| `COLLECTION_BATCH_TOO_MANY_OPS` | 422 | A batch can contain at most 500 writes. |
| `COLLECTION_CONVERSION_ALREADY_RUNNING` | 409 | This collection is already being converted. |
| `COLLECTION_CONVERT_COLUMNS_INVALID` | 422 | The column choices are not valid. |
| `COLLECTION_CONVERT_EMPTY` | 422 | The collection has no records to convert. |
| `COLLECTION_CONVERT_TOO_MANY_RECORDS` | 422 | A collection with more than 50,000 records cannot be converted to a table. |
| `COLLECTION_CONVERT_VISIBILITY_RESTRICTED` | 422 | Only a collection visible to its whole team space can be converted to a table. |
| `COLLECTION_CURSOR_INVALID` | 400 | This page link is not valid for this query. Run the query again from the first page. |
| `COLLECTION_DEFAULT_TTL_INVALID` | 422 | The default expiry must be between 1 second and 10 years. |
| `COLLECTION_EXPORT_TOO_MANY_COLUMNS` | 422 | The records have more than 1,000 different fields; export as JSON instead. |
| `COLLECTION_IMPORT_ALREADY_RUNNING` | 409 | Another import into this collection is still running. |
| `COLLECTION_IMPORT_KEY_FIELD_INVALID` | 422 | A key field can only be used with plain records. |
| `COLLECTION_IMPORT_TOO_MANY_PENDING` | 409 | This collection already has 5 imports waiting for their files. Start one, or wait for one to expire. |
| `COLLECTION_IMPORT_UPLOAD_INCOMPLETE` | 409 | The file has not finished uploading, or its size differs from the size you declared. |
| `COLLECTION_INDEX_BROKEN_BY_DATA` | 409 | Existing records share values in this field. Fix them, then make it unique. |
| `COLLECTION_INDEX_BUILDING` | 409 | The index on this field is still being built. Retry shortly. |
| `COLLECTION_INDEX_EXISTS` | 409 | This field already has an index. |
| `COLLECTION_INDEX_LIMIT_REACHED` | 409 | A collection can have at most 5 indexes. Remove one first. |
| `COLLECTION_INDEX_NOT_FOUND` | 404 | No index exists in this slot. |
| `COLLECTION_IO_JOB_STATE_INVALID` | 409 | This job cannot be started in its current state. |
| `COLLECTION_MOVE_ACROSS_TEAM_SPACES_UNSUPPORTED` | 409 | Collections cannot be moved to another Team Space yet. |
| `COLLECTION_PATCH_EMPTY` | 422 | Provide a merge patch or at least one field operation. |
| `COLLECTION_PATCH_OPS_CONFLICT` | 422 | Two operations target overlapping fields. |
| `COLLECTION_PATCH_TYPE_MISMATCH` | 422 | An operation does not fit the type of the field it targets. |
| `COLLECTION_PATH_INVALID` | 422 | The field path is not valid. |
| `COLLECTION_PRECONDITION_INVALID` | 422 | The version condition is not valid. |
| `COLLECTION_QUERY_INVALID` | 422 | The query is not valid. Check the filter and sort. |
| `COLLECTION_QUERY_NEEDS_INDEX` | 422 | Sorting or filtering this field by range needs an index on it. |
| `COLLECTION_QUERY_RANGE_NOT_FIRST_SORT` | 422 | When filtering a field by range, sort by that field. |
| `COLLECTION_QUERY_TIMEOUT` | 422 | The query took longer than 5 seconds. Narrow the filter or add an index. |
| `COLLECTION_QUERY_TOO_MANY_RANGES` | 422 | A query can filter only one field by range. |
| `COLLECTION_QUERY_VALUE_TYPE_MISMATCH` | 422 | The value does not match the type of the field's index. |
| `COLLECTION_RECORD_BUSY` | 409 | The record is being changed by another request. Retry shortly. |
| `COLLECTION_RECORD_DATA_NOT_OBJECT` | 422 | A record must be a JSON object. |
| `COLLECTION_RECORD_EXISTS` | 409 | A record with this key already exists. |
| `COLLECTION_RECORD_FIELD_NAME_INVALID` | 422 | Field names must be 1-256 characters. |
| `COLLECTION_RECORD_KEY_INVALID` | 422 | Record keys use 1-256 letters, digits or _ . : @ ~ - and may not start with __. |
| `COLLECTION_RECORD_LIMIT_REACHED` | 409 | This collection holds 250,000 records, its fixed limit. Nothing has been removed. Delete records you no longer need or set them to expire. |
| `COLLECTION_RECORD_NOT_FOUND` | 404 | No record with this key exists in the collection. |
| `COLLECTION_RECORD_TOO_DEEP` | 422 | The record is nested more than 20 levels deep. |
| `COLLECTION_RECORD_TOO_LARGE` | 413 | The record is larger than 256 KB. |
| `COLLECTION_RECORD_TOO_MANY_FIELDS` | 422 | The record has more than 2,000 fields. |
| `COLLECTION_RECORD_TTL_INVALID` | 422 | Set one expiry: seconds from now (up to 10 years), a future date with a time zone, or none. |
| `COLLECTION_RECORD_VALUE_INVALID` | 422 | The record contains a value that cannot be stored (an infinite number, a null character or an invalid text character). |
| `COLLECTION_RECORD_VERSION_CONFLICT` | 412 | The record changed since you read it. Read it again and retry. |
| `COLLECTION_UNIQUE_UNSUPPORTED_TYPE` | 422 | Only text and number fields can be unique. |
| `COLLECTION_UNIQUE_VIOLATION` | 409 | Another record already has this value in a field that must be unique. |
| `COLLECTION_UPDATE_EMPTY` | 422 | Provide at least one setting to change. |
| `DATABASE_CURSOR_INVALID` | 422 | The page cursor is invalid or belongs to a different query. Start again from the first page. |
| `DATABASE_FILTER_OPERATOR_INVALID` | 422 | This filter operator cannot be used with this column. |
| `DATABASE_GROUP_PROPERTY_NOT_FOUND` | 422 | The grouping column does not exist in the table. |
| `DATABASE_NOT_FOUND` | 404 | That database could not be found. It may have been removed, or you may not have access to it. |
| `DATABASE_PAGE_SIZE_EXCEEDED` | 422 | The requested page size is out of range. |
| `DATABASE_PROPERTY_NOT_FOUND` | 422 | This column does not exist in the table. |
| `DATABASE_PROPERTY_VALUE_INVALID` | 422 | A value does not fit its column's type. |
| `DATABASE_QUERY_COLUMN_WITHHELD` | 422 | This column is hidden from you, so it cannot be used to filter, sort or group. |
| `DATABASE_QUERY_COMPUTED_TOO_BROAD` | 422 | Filtering or sorting on a formula or rollup column needs a narrower query. Add a filter on another column first. |
| `DATABASE_QUERY_INVALID` | 422 | That query is not valid for this database. |
| `DATABASE_QUERY_TIMEOUT` | 504 | This query took too long. Narrow it with a filter and try again. |
| `DATABASE_RELATED_ACCESS_DENIED` | 403 | You do not have access to the table this relation column points at. |
| `DATABASE_RELATED_COLUMN_INVALID` | 422 | That column of a related table cannot be used here. Pick a column of the table the relation column points at. |
| `DATABASE_REQUEST_LIMIT_REACHED` | 429 | This table or collection reached its requests for today. It resets at 00:00 UTC (see the `Retry-After` header); an organization admin can raise Requests per day in Organization settings. |
| `DATABASE_REQUIRED_MISSING` | 422 | A required column is empty. Fill it in and save again. |
| `DATABASE_ROW_LIMIT_EXCEEDED` | 409 | This database has reached its row limit. Nothing has been removed. To add more rows, an organization admin can raise Row limit per table in Organization settings, or remove rows you no longer need. |
| `DATABASE_ROW_NOT_FOUND` | 404 | That record could not be found. It may have been removed. |
| `DATABASE_ROW_VALIDATION_FAILED` | 422 | The row could not be saved: check the column names and the number of rows sent. |
| `DATABASE_SCHEMA_INVALID` | 422 | The table's column definition is invalid. |
| `DATABASE_STORAGE_LIMIT_REACHED` | 409 | This table or collection reached its storage limit, so nothing new can be added. Nothing has been removed. Delete rows or records you no longer need, or ask an organization admin to raise Storage per database in Organization settings. |
| `DATABASE_SORT_PROPERTY_NOT_FOUND` | 422 | The sort column does not exist in the table. |
| `DATABASE_TOTALS_INVALID` | 422 | Those totals cannot be computed. Check the group-by columns and the totals asked for. |
| `DATABASE_UNIQUE_VIOLATION` | 409 | Another row already has this value in a column that must be unique. |
| `FLOW_NODE_NOT_FOUND` | 404 | That node is not in this automation, or is not one that adds rows to a table. |
| `FLOW_NOT_FOUND` | 404 | The requested flow could not be found. |
| `ITEM_NOT_FOUND` | 404 | Item not found. |
| `ITEM_PERMANENTLY_DELETED` | 409 | This item was permanently deleted and cannot be restored. |
| `ITEM_SPACE_DELETED` | 409 | The workspace this item lives in was deleted, so the item cannot be opened. Restore the workspace from Workspaces > Trash and everything inside it comes back. |
| `OPTIMISTIC_LOCK_CONFLICT` | 409 | This item was modified by someone else. Please reload and try again. |
| `REQUEST_TOO_LARGE` | 413 | The request is too large. Please reduce its size and try again. |
| `STORAGE_LIMIT_EXCEEDED` | 413 | Your organisation has reached its storage limit, so new uploads are paused for now. Nothing has been removed — every file you already have stays exactly where it is and still opens, downloads and shares as normal. To free up room, empty your trash. To raise the limit, add more storage. |
| `TEAM_SPACE_NOT_FOUND` | 404 | Team Space not found. |
| `COLLECTION_IMPORT_ENTRY_INVALID` | inside `issues` | This entry is not an object with a data object. |
| `COLLECTION_IMPORT_KEY_FIELD_MISSING` | inside `issues` | This entry has no usable value in the key field. |
| `COLLECTION_CONVERT_VALUE_BLANKED` | inside `issues` | A value did not fit its column type and was left empty. |
| `COLLECTION_CONVERT_FIELD_NOT_COPIED` | inside `issues` | A field has no column in the table, so its value was not copied. |


## Page Save Errors

Returned by [Apply block operations to a page](/docs/api-reference/smoc/pages/patch-blocks) when it is sent an `Idempotency-Key`, or when it cannot commit in time. `PAGE_PAYLOAD_RESERVED_FORMAT` is returned by [Upload item payload](/assets/put-payload.ebcdc4f1c9e210a5f25cbaacf4373a64b770046bf5dc4bffb806fb6a5b20b5b2.98368ece.md) and [Finalize chunked payload upload](/assets/finalize-chunks.056f1bf0a7dea36daadf65ee5b551817ac692056687d343e8b4d02a091cc1946.98368ece.md) on a page item.

| Code | Status | Message |
|  --- | --- | --- |
| `IDEMPOTENT_IN_FLIGHT` | 409 | Your previous save of this page is still being applied. Try again in a moment; it will not be applied twice. |
| `IDEMPOTENCY_KEY_REUSED` | 422 | This save reused the identifier of a different save, so it was not applied. Send it again as a new save. |
| `IDEMPOTENCY_KEY_INVALID` | 422 | This save carried an identifier the server cannot accept. Send it again with a new identifier. |
| `PAGE_PATCH_DEADLINE_EXCEEDED` | 503 | Saving took too long, so nothing was saved and the page is unchanged. Try again. |
| `PAGE_PAYLOAD_RESERVED_FORMAT` | 422 | This file uses a format the server reserves for its own storage, so it cannot be saved as a page. Save the page's content instead. |


## Read State Errors

Returned by [Mark an item read](/docs/api-reference/smoc/read-states/mark-read) and [Get who has read an item](/docs/api-reference/smoc/read-states/get-seen-by).

| Code | Status | Message |
|  --- | --- | --- |
| `READ_STATE_REVISION_NOT_OF_ITEM` | 422 | That version does not belong to this document. Reload it and try again. |
| `SEEN_BY_NOT_PERMITTED` | 403 | Only people who manage this document's sharing can see who has viewed it. |


## Forge Machine Errors

Returned by the calls that register and list a person's machines and Forge downloads: [Register this Forge install](/assets/register-device.ead7116afe73cba42f13cf8bf6fa437802e9d8362709690d047e7bfcca1b191b.23c4b6e8.md), [List your Forge machines](/assets/list-devices.62ad30cfc6c2165a0f0f6bda0b2f5e462b87fbd0c457ae996c017cd0364b23f2.23c4b6e8.md), [Change a Forge machine](/assets/update-device.ef75f1f907de377c0373bde922ebf9529bb91d9661f75716d56ae91f64d34f91.23c4b6e8.md), [Keep a Forge machine online](/assets/heartbeat-device.ba2ff2149a75bd0b22356e6de79ced109ef1b953086b3f7463ef74d8ae041d01.23c4b6e8.md), [Remove a Forge machine](/assets/delete-device.ecbb0b08eca956694ca111cf51383715b5e03b3da438a612731d9ee2d32faad2.23c4b6e8.md), [List Forge downloads](/assets/list-downloads.6b7c5b34422f8e0c784dd8b159c5aede3c15d264d113c0fcb2d3c7cda4eac3ed.23c4b6e8.md) and [Email yourself a Forge download link](/assets/email-download-link.12883ea39cda16b44325c422d3d14ffefe839f9950df71f5ff76764a42fe84a2.23c4b6e8.md).

| Code | Status | Message |
|  --- | --- | --- |
| `FORGE_DEVICE_NOT_FOUND` | 404 | That machine isn't in your Forge machines any more. |
| `FORGE_DEVICE_REVOKED` | 410 | This machine was removed from your Forge machines. Add it again to use it. |
| `FORGE_DEVICE_LIMIT_REACHED` | 409 | You already have 25 machines. Remove one you no longer use, then try again. |
| `FORGE_RELAY_HOST_ID_TAKEN` | 409 | Another machine is already using this machine's connection key. |
| `FORGE_DEVICE_INVALID` | 422 | This machine sent details Forge machines can't use. Update Forge and try again. |
| `FORGE_DOWNLOADS_UNAVAILABLE` | 503 | Downloads can't be listed right now. Try again in a moment. |
| `FORGE_DOWNLOAD_NOT_OFFERED` | 422 | There is no Forge download for that computer yet. |
| `FORGE_DOWNLOAD_EMAIL_UNVERIFIED` | 422 | Verify your email address first, then we can send you the link. |


## Forge Server Link Errors

Returned by the calls that link a Linux server and keep it signed in: [Create a server link code](/assets/create-server-link.b2764618e246fc23fbef9a028e99b650a1c082241cb9cb291ad15382fff1e8d8.23c4b6e8.md), [Read a server link code](/assets/get-server-link.493f89fa2641f785c7fce25b29fc4a8203e5bcfdf49dbf5bfbc522faa0811e78.23c4b6e8.md), [Cancel a server link code](/assets/cancel-server-link.b0fd7a03af6385101d30d408a76a5d385ac75a84479c82d76965e11867435c9f.23c4b6e8.md), [Redeem a server link code](/assets/redeem-server-link.f2748b4d7dcc49d005994e3754e415f0d0594ea976f709ceb2ea0fae31a9a810.23c4b6e8.md), [Refresh a server's credentials](/assets/refresh-device-token.9245aa82e221a149d4ec9ef54224401e44cf52824627d1af843ea8243d82856c.23c4b6e8.md), [Unenrol this server](/assets/unenrol-device.17bc1fc82084c79630226284946c644ca2a61a4d691653e62bf8c9cacbdcf7eb.23c4b6e8.md) and [Stream a server's events](/assets/stream-device-events.513806b1488be1b2951f13b220e770e75a5ae066092aa6088fb143fd270473e2.23c4b6e8.md).

| Code | Status | Message |
|  --- | --- | --- |
| `FORGE_LINK_CODE_INVALID` | 404 | That link code doesn't work. It may have expired or been used already. Create a new one in Forge and try again. |
| `FORGE_SERVER_LINK_NOT_FOUND` | 404 | That server link isn't available any more. Create a new one. |
| `FORGE_LINK_OWNER_INELIGIBLE` | 403 | The person who created this link code can't add servers to Forge any more. |
| `FORGE_DEVICE_CREDENTIAL_INVALID` | 401 | This server is no longer linked to Forge. Link it again with a new code. |
| `FORGE_DEVICE_CREDENTIAL_REUSED` | 401 | This server's sign-in was used twice, so it was signed out to keep it safe. Link it again with a new code. |
| `FORGE_DEVICE_OWNER_INELIGIBLE` | 403 | The owner of this server can't use Forge in this organization any more. |


## Forge SSH Setup Errors

Returned by the calls that follow a Windows PC turning on SSH: [Create an SSH setup](/assets/create-ssh-setup.34180209f1ba831295f68ce4bfdc202e2fc8f93df4ed9c0b2eef37736ed46116.23c4b6e8.md), [Report an SSH setup step](/assets/report-ssh-setup-step.137af4e3e0617920c510f31e108ac5e1ab2e14b437c42224a919dd796cee4f7d.23c4b6e8.md), [Read an SSH setup](/assets/get-ssh-setup.ba1752dbe4f8cd016639899378af3ce96a712a57f9394e786ad8327ef615cbce.23c4b6e8.md) and [Cancel an SSH setup](/assets/cancel-ssh-setup.58bce5ff4c379faafa11e4ee434c60e9328b80e1829c7112f363497bf1cd7fc9.23c4b6e8.md).

| Code | Status | Message |
|  --- | --- | --- |
| `FORGE_SSH_SETUP_UNKNOWN` | 404 | That setup code doesn't work. It may have expired or been cancelled. Start the setup again in Forge. |
| `FORGE_SSH_SETUP_FINISHED` | 409 | This setup has already finished, so no more steps can be reported. |
| `FORGE_SSH_SETUP_NOT_FOUND` | 404 | That SSH setup isn't available any more. Start a new one in Forge. |


## Forge Relay Errors

Returned by [Read the Forge relay settings](/assets/get-relay-config.fd95418fe0f706a9c11c3402ab05df66b532b7f21ccd3f52a38297e5345a2b48.23c4b6e8.md), [Get a relay host token](/assets/create-relay-token.cd052a9a3d46769ff9f3947afce63c3418b7ab5cfff208d1a88d412eedef85ad.23c4b6e8.md) and [Read the relay token signing keys](/assets/get-relay-jwks.63f0e8b274089dd990757ec156ed8cfb594261a3cf42757b4b7c5aace69fd0a5.23c4b6e8.md). `FORGE_RELAY_UNAVAILABLE` carries a `Retry-After` header and `details.reason` says why.

| Code | Status | Message |
|  --- | --- | --- |
| `FORGE_RELAY_HOST_ID_MISMATCH` | 422 | This machine's connection key doesn't match the one it registered. Restart Forge so it can register again. |
| `FORGE_RELAY_UNAVAILABLE` | 503 | Connecting through Aitronos isn't possible right now. Forge will try again shortly. |


## Forge Connection Errors

Returned by the calls that connect two machines: [Ask a machine for a connection offer](/assets/request-offer.ba131d21f11c6c27d4105da6edfbbe292683792d99fd53c37b3c6a8a62d7dbbc.23c4b6e8.md), [Read a connection offer request](/assets/get-offer-request.042a609c66f3b4655d5b71d9816172a0baa4c2f371f0b2cfe8a3d94e7c7fe10f.23c4b6e8.md), [List the connection offers a machine still has to answer](/assets/list-waiting-offer-requests.dcc7cba24013b4476391694600ca548deebdad83dabc1a13d25cf53434dae349.23c4b6e8.md), [Seal a connection offer](/assets/seal-offer.2800eaf5f55f272727ea87058a399316fe2ad78ad24ba7ea9b6187f2bd46bb6a.23c4b6e8.md), [Fail a connection offer](/assets/fail-offer.d021587fd1e8e112699714781a192b99254c44437a9891bd441aab052e30613e.23c4b6e8.md), [Collect a sealed connection offer](/assets/collect-offer.aa46bfdd81db06f0f2d2c686708b1b2526d2fe9757eced08e8dfb2029d4071bd.23c4b6e8.md), [Start a connection session](/assets/start-session.2013acb5d4720e6eab6b2b5f4e07dffe966faec8461785a675779ec30be87f69.23c4b6e8.md), [End a connection session](/assets/end-session.b010613d40bdc315f021ae5e47efc933be9e4a25a0caebbe10f48402e3e618f2.23c4b6e8.md) and [List connection sessions](/assets/list-sessions.1118185504da14a805aacc2fc396b2d2090d97a02ff635b2e7baee9b5fc019e7.23c4b6e8.md). `FORGE_OFFER_UNAVAILABLE` carries a `Retry-After` header. `FORGE_DEVICE_NOT_A_HOST` is also returned by [Get a relay host token](/assets/create-relay-token.cd052a9a3d46769ff9f3947afce63c3418b7ab5cfff208d1a88d412eedef85ad.23c4b6e8.md), and `FORGE_PHONE_OWN_MACHINES_ONLY` by [Ask a colleague for access to a machine](/assets/request-access.33470a48a332d8197b8cd451c011f949934df988fd82dbd45c712db1ca7be215.23c4b6e8.md).

| Code | Status | Message |
|  --- | --- | --- |
| `FORGE_GRANT_REQUIRED` | 403 | You need the owner's permission to connect to this machine. Ask them first. |
| `FORGE_OFFER_REQUEST_OPEN` | 409 | Forge is already connecting to this machine. Wait a moment and try again. |
| `FORGE_OFFER_SELF` | 422 | A machine can't connect to itself. |
| `FORGE_OFFER_NOT_FOUND` | 404 | That connection request isn't available any more. Connect again. |
| `FORGE_OFFER_NOT_WAITING` | 409 | This connection request was already answered. |
| `FORGE_OFFER_NOT_READY` | 409 | The other machine hasn't answered this connection request yet. |
| `FORGE_OFFER_EXPIRED` | 410 | This connection request timed out. Connect again. |
| `FORGE_OFFER_GONE` | 410 | This connection was already picked up. Connect again if it didn't open. |
| `FORGE_OFFER_TOO_LARGE` | 413 | This machine sent a connection answer that is too large. Update Forge and try again. |
| `FORGE_OFFER_SENDER_KEY_MISMATCH` | 422 | This machine's connection key doesn't match the one it registered. Restart Forge so it can register again. |
| `FORGE_OFFER_INVALID` | 422 | This machine sent a connection answer Forge can't use. Update Forge and try again. |
| `FORGE_OFFER_UNAVAILABLE` | 503 | Connecting to machines isn't possible right now. Try again in a moment. |
| `FORGE_DEVICE_NOT_A_HOST` | 422 | A phone can't be connected to. Pick one of your computers. |
| `FORGE_OFFER_SCOPE_NOT_ALLOWED` | 422 | A phone can only open a mobile connection to a computer. |
| `FORGE_PHONE_OWN_MACHINES_ONLY` | 403 | A phone can only connect to your own computers. |
| `FORGE_SESSION_NOT_FOUND` | 404 | That session isn't available any more. |
| `FORGE_SESSION_OFFER_NOT_COLLECTED` | 409 | This connection wasn't completed, so no session can start from it. Connect again. |


## Forge Colleague Access Errors

Returned by the calls that let one person work on a colleague's machine: [Read the organization's Forge machines settings](/assets/get-machines-settings.b16c3cf3baa6b185029b5ba687b6c2c3691ba777d61db722bbfc404fa5edfafa.23c4b6e8.md), [Change the organization's Forge machines settings](/assets/update-machines-settings.77fdde8d2574b5452658b9190e7d833639243da139a679c9c41a8b66cb003bee.23c4b6e8.md), [List colleagues' machines](/assets/list-colleague-devices.8a5bd71843f172fec8bb9e0cf32cc5b206d305ab96ba5030fb880fcc2e0195f5.23c4b6e8.md), [Ask a colleague for access to a machine](/assets/request-access.33470a48a332d8197b8cd451c011f949934df988fd82dbd45c712db1ca7be215.23c4b6e8.md), [List access requests](/assets/list-access-requests.ca06b90c0bf07019b5c7920ef7c07aad7a2ea4bdb5b865cc87dece5b66c3cac9.23c4b6e8.md), [Answer an access request](/assets/answer-access-request.1845f4159c59abce6726660a25331e3285426a6ebf5a218d7ba22ce5305f7170.23c4b6e8.md), [Cancel an access request](/assets/cancel-access-request.9feaa648dbac2bcd3e992fd0476993584e2086c9de91aeca44dc604e161419bc.23c4b6e8.md), [List access grants](/assets/list-access-grants.bd6c3975dc39ea2c1a93a3cfbaac65308de3680ff6ea4d021e289c72cc120ff1.23c4b6e8.md) and [Revoke an access grant](/assets/revoke-access-grant.d2e1cc723739a5d9fb1fdd3be94c3ca164761ef05118088faa2162c01c259e07.23c4b6e8.md). `FORGE_ACCESS_REQUEST_COOLDOWN` and `FORGE_ACCESS_UNAVAILABLE` carry a `Retry-After` header.

| Code | Status | Message |
|  --- | --- | --- |
| `FORGE_COLLEAGUE_ACCESS_DISABLED` | 403 | Working on colleagues' machines isn't available here. |
| `FORGE_ACCESS_REQUEST_OPEN` | 409 | You already asked for this machine. Wait for the answer. |
| `FORGE_ACCESS_ALREADY_GRANTED` | 409 | You already have access to this machine. |
| `FORGE_ACCESS_REQUEST_OWN_DEVICE` | 422 | This is one of your own machines. You can connect without asking. |
| `FORGE_ACCESS_REQUEST_COOLDOWN` | 429 | Your request was just declined. You can ask again in a minute. |
| `FORGE_ACCESS_REQUEST_NOT_PENDING` | 409 | This request was already answered. |
| `FORGE_ACCESS_REQUEST_EXPIRED` | 410 | This request timed out. |
| `FORGE_ACCESS_REQUEST_NOT_FOUND` | 404 | That request isn't available any more. |
| `FORGE_ACCESS_GRANT_NOT_FOUND` | 404 | That access isn't available any more. |
| `FORGE_ACCESS_UNAVAILABLE` | 503 | Asking for access isn't possible right now. Try again in a moment. |


## 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)