Skip to main content

Error Types Reference

This page provides a comprehensive reference for problem type URIs used by Tourfold REST APIs. These follow RFC 9457 and include machine-readable URIs.

GraphQL errors are different: they are returned in GraphQL's errors array rather than as an HTTP problem document. Every error carries a stable Type URI in extensions.code; parse and validation failures use graphql/invalid-query. See GraphQL Errors.

Error Type Structure​

Error types follow this structure:

  • Category errors: https://problems.tourfold.com/{error-slug} (e.g., https://problems.tourfold.com/validation-failed)
  • Namespaced errors: https://problems.tourfold.com/{category}/{error-slug} (e.g., https://problems.tourfold.com/tours/tour-ended)

Generic Errors​

These errors are general-purpose and can occur across the API.

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/unknown-errorUnknown errorAn unexpected error occurred500
https://problems.tourfold.com/invalid-inputInvalid inputThe provided input was not valid400
https://problems.tourfold.com/business-rule-violationBusiness rule violationThe request violates business rules422
https://problems.tourfold.com/not-foundNot foundThe requested resource was not found404
https://problems.tourfold.com/method-not-allowedMethod not allowedThe path exists, but the requested HTTP method is not supported. The Allow header and data.supported list the supported methods.405
https://problems.tourfold.com/not-acceptableNot acceptableNo representation of the resource matches the Accept header406
https://problems.tourfold.com/unsupported-media-typeUnsupported media typeThe request body's media type is not accepted. data.content_type contains the rejected value and data.supported lists accepted media types.415
https://problems.tourfold.com/authentication-requiredAuthentication requiredValid authentication credentials are required. The cause is surfaced in data.reason (token_missing, token_expired, token_invalid) and mirrored in the WWW-Authenticate header.401
https://problems.tourfold.com/access-deniedAccess deniedYou don't have permission to perform this action. The cause is surfaced in data.reason (missing_grant, not_owner, not_member, plan_restricted, tenant_scope, self_target, wrong_actor_type, device_proof_missing, device_proof_invalid); grant-based denials also carry data.required_grants when the required grants are statically known.403
https://problems.tourfold.com/user-deactivatedUser deactivatedThis user account is deactivated in this workspace. The token is valid, so signing in again does not help; data.tenant_id names the workspace.403
https://problems.tourfold.com/tenant-disabledTenant disabledThis tenant is disabled403
https://problems.tourfold.com/tenant-billing-lockedTenant billing lockedThis tenant is locked because billing requires attention402
https://problems.tourfold.com/action-not-allowedAction not allowedA capability is unavailable to the caller. On plugin routes, the tenant's plugin is disabled or its enablement cannot be resolved: data.reason is plan_restricted, data.plugin_name identifies the plugin, and data.resolution_reason explains the decision. On core routes an enabled plugin owns (for example device, vehicle-device association and work-phone user writes while Γ–AMTC is enabled): data.reason is plugin_managed, data.plugin_name identifies the plugin, and data.managed_by names the plugin endpoint to use instead.403
https://problems.tourfold.com/validation-failedValidation failedOne or more fields failed validation422
https://problems.tourfold.com/resource-conflictResource conflictThe request conflicts with the current state409
https://problems.tourfold.com/rate-limit-exceededRate limit exceededRate limit exceeded for this endpoint429
https://problems.tourfold.com/too-many-requestsToo many requestsToo many requests in the time window429
https://problems.tourfold.com/burst-limit-exceededBurst limit exceededBurst rate limit exceeded429
https://problems.tourfold.com/not-uniqueNot uniqueThe provided details were not unique422
https://problems.tourfold.com/payload-too-largePayload too largeThe request payload exceeds the maximum allowed size413
https://problems.tourfold.com/not-implementedNot implementedThis functionality is not implemented501
https://problems.tourfold.com/upstream-service-unavailableUpstream service unavailableAn upstream service is temporarily unavailable503
https://problems.tourfold.com/login-failedLogin failedAuthentication credentials are invalid. Returned for a rejected credential-based login, as opposed to an absent or unusable bearer token (authentication-required).401
https://problems.tourfold.com/client-connection-brokenClient connection brokenThe client connection was interrupted500
https://problems.tourfold.com/empty-collection-argumentEmpty collection argumentThe provided collection argument must not be empty422

Generic Error Examples​

{
"type": "https://problems.tourfold.com/validation-failed",
"title": "Validation failed",
"detail": "One or more fields failed validation",
"status": 422
}
{
"type": "https://problems.tourfold.com/not-found",
"title": "Not found",
"detail": "The requested resource was not found",
"status": 404
}

Definition Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/definitions/schema-lockedDefinition schema is lockedThe system or a plugin owns the definition's authored schema. Editing or deleting it is prohibited, including changing labels or display templates; a patch of only icon and color is allowed. data.definition_slug, data.managed_by and optional data.plugin_id identify its ownership; record writability is independent.409

Validation Sub-Problem Types​

A top-level validation-failed problem can contain an errors[] array. Each entry uses one of these stable, cross-feature type URIs when the standard meaning applies. Its pointer identifies the rejected request field using JSON Pointer syntax. Feature-specific validation types are documented in their feature section instead.

Type URIMeaning
https://problems.tourfold.com/field-validation-errorThe field failed validation and no narrower standard type applies.
https://problems.tourfold.com/field-requiredThe field is missing, null, empty, or blank.
https://problems.tourfold.com/field-too-largeA numeric value is above its allowed maximum.
https://problems.tourfold.com/field-too-smallA numeric value is below its allowed minimum.
https://problems.tourfold.com/field-size-invalidA string or collection length is outside its allowed bounds.
https://problems.tourfold.com/field-type-invalidThe value has the wrong JSON type or shape.
https://problems.tourfold.com/field-out-of-rangeThe value is outside the field's allowed range.
https://problems.tourfold.com/invalid-emailThe value is not a valid email address.
https://problems.tourfold.com/invalid-phone-numberThe value is not a valid international phone number.
https://problems.tourfold.com/invalid-enum-valueThe value is not one of the allowed enum members.
https://problems.tourfold.com/not-uniqueThe value duplicates a record whose field must be unique.

GraphQL Errors​

These surface inside the GraphQL response envelope, not as an HTTP problem document: a GraphQL failure is still HTTP 200 with an errors array.

Which errors carry a code. Every error Tourfold raises carries extensions.code β€” the Type URI, the same value a REST error carries in type β€” so both surfaces are keyed off one identifier. title and (when present) data sit flat beside it; there is deliberately no wrapping problem object, matching Shopify and GitHub. The human text lives in message and is not repeated as detail.

Errors raised by the GraphQL engine itself β€” a malformed document, an unknown field, a wrongly typed argument β€” are augmented with graphql/invalid-query. Their original message, locations, and engine classification remain available, but clients never need to parse English text to recognize an invalid document.

The graphql/ namespace is not the whole catalog. Only failures with no REST equivalent take it. Everything else reuses the type it already has elsewhere on this page β€” a rejected filter value is validation-failed, with the offending field named under extensions.errors, and an unexpected server-side failure is unknown-error. A client that already handles Tourfold's REST errors needs no second vocabulary for GraphQL.

There is no status field, unlike the REST tables on this page. The response is always HTTP 200, so there would be no status to report; match on code instead.

An error may list sub-errors under extensions.errors. These carry only what varies per occurrence (code, message, path, data) and do not nest further. path addresses a field the way GraphQL addresses everything else, so one payload never mixes field paths with JSON Pointers; converting to a REST problem document renders it as an RFC 6901 pointer.

Type URITitleDescription
https://problems.tourfold.com/graphql/invalid-queryInvalid GraphQL queryThe document could not be parsed or validated against the workspace schema
https://problems.tourfold.com/graphql/query-too-deepQuery too deepThe query nests more levels than the configured maximum depth
https://problems.tourfold.com/graphql/query-too-complexQuery too complexThe query is estimated to materialise more rows than the configured budget allows
https://problems.tourfold.com/graphql/query-timeoutQuery timed outThe query exceeded the configured execution deadline
https://problems.tourfold.com/graphql/filter-too-deepFilter too deepThe where argument nests more levels than the configured maximum filter depth
https://problems.tourfold.com/graphql/invalid-cursorInvalid cursorThe supplied pagination cursor was not produced by this API
https://problems.tourfold.com/graphql/invalid-paginationInvalid pagination argumentsThe supplied pagination arguments are contradictory or out of range

Each reports in data what a client needs in order to adapt without guessing: depth and cost errors give the measured value next to the limit, query-timeout gives the configured deadline in timeout_ms, invalid-cursor echoes the cursor it rejected, and invalid-pagination echoes the arguments that conflicted.

{
"data": null,
"errors": [
{
"message": "Query is estimated to materialise 3003001 rows, above the budget of 100000. A connection multiplies its subtree by its page size β€” request smaller pages or select fewer nested fields.",
"extensions": {
"code": "https://problems.tourfold.com/graphql/query-too-complex",
"title": "Query too complex",
"data": { "cost": 3003001, "limit": 100000 }
}
}
]
}

Pagination Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/pagination/invalid-page-numberInvalid page numberPage number must be non-negative (0 or greater)422
https://problems.tourfold.com/pagination/invalid-page-sizeInvalid page sizePage size must be between 1 and 1000422

Time Range Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/time-range/from-after-toInvalid time rangeThe 'from' parameter must be before the 'to' parameter422

Activity Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/activities/wrong-activity-typeWrong activity typeWrong activity type422

AI Assistant Errors​

These errors come from the in-app AI assistant ("Ask Rob"). They surface both as HTTP error responses (REST endpoints under /frontend/v2/ai-assistant/...) and inside the turn.error SSE event payload as an embedded ProblemDetail β€” the wire shape is identical.

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/ai-assistant/assistant-disabledAI assistant is disabledThe AI assistant is disabled for this tenant. A tenant administrator can re-enable it from the AI assistant settings.403
https://problems.tourfold.com/ai-assistant/turn-in-progressAI assistant turn already in progressAnother AI assistant turn is already in progress for this session. Wait for it to finish or cancel it before sending another message. The conflicting sessionId is included in data.409
https://problems.tourfold.com/ai-assistant/provider-rate-limitedAI assistant provider is rate limitedThe AI assistant is temporarily at capacity because the upstream AI provider rejected the turn for a capacity reason on the shared key (rate limit, overload, or account quota) β€” not the tenant's own spend budget. The message can be retried after a short wait.503

Address Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/addresses/opening-hours-wrong-formatOpening hours wrong formatOpening hours have a wrong time format422

Filestore/File Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/filestore/file-not-foundFile not foundThe referenced file or rendition is not available.404
https://problems.tourfold.com/filestore/file-deletedFile deletedThe referenced file has been deleted.422
https://problems.tourfold.com/filestore/storage-object-missingStorage object missingThe file is recorded as uploaded, but its underlying object is missing from storage β€” a data-integrity gap, distinct from a never-existed id (404). The data payload names the offending object: bucket, storageKey, and β€” on rendition read paths β€” fileId, renditionId, alias.410
https://problems.tourfold.com/filestore/file-not-attachableFile is not attachableCollapsed 404 covering every "you can't use this file" failure (id does not exist, wrong source key, wrong uploader, already linked). The collapse is intentional β€” UUID leaks are the threat model.404
https://problems.tourfold.com/filestore/rendition-source-not-supportedRendition source not supportedRenditions can only be generated from image and PDF sources.422
https://problems.tourfold.com/filestore/rendition-target-format-not-supportedRendition target format not supportedThe requested target format is not supported by the source-specific rendition converter.422
https://problems.tourfold.com/filestore/rendition-source-decode-failedRendition source decode failedThe source file could not be decoded for rendition generation (corrupted or unsupported encoding).422
https://problems.tourfold.com/filestore/rendition-pdf-emptyRendition source PDF is emptyThe source PDF has no pages.422
https://problems.tourfold.com/filestore/rendition-alias-reservedRendition alias is reservedThe alias original is reserved for the canonical original rendition.422
https://problems.tourfold.com/filestore/upload-content-emptyUpload content is emptyThe upload payload is empty.422
https://problems.tourfold.com/filestore/upload-mime-type-blankUpload MIME type is missingA non-blank MIME type is required for the upload.422
https://problems.tourfold.com/filestore/upload-original-file-name-blankUpload original file name is missingA non-blank original file name is required for the upload.422
https://problems.tourfold.com/filestore/upload-rejectedUpload rejectedThe upload was rejected during completion β€” size or MIME type does not match the declared values.422
https://problems.tourfold.com/filestore/storage-purge-incompleteStorage purge incompleteA bulk purge could not delete every matching object after retries; some objects remain in storage. The data payload names the bucket, prefix, and undeletedCount.500

Usage Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/usage/limit-exceededUsage limit exceededThe requested operation would exceed the tenant's configured usage limit422

Document Management Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/document-management/invalid-nameInvalid nameThe supplied folder or document name is invalid (empty after trim, reserved name, forbidden character, or exceeds the length limit).422
https://problems.tourfold.com/document-management/name-takenName takenA live sibling folder or document already uses this name.409
https://problems.tourfold.com/document-management/parent-not-foundParent folder not foundThe referenced parent folder does not exist.404
https://problems.tourfold.com/document-management/folder-not-foundFolder not foundThe referenced folder does not exist.404
https://problems.tourfold.com/document-management/move-into-descendantMove into descendantA folder cannot be moved into itself or one of its descendants.422
https://problems.tourfold.com/document-management/move-across-managed-boundaryMove across managed boundaryA user folder cannot be moved into a managed subtree (e.g. /objects/...), and a managed folder cannot be moved out of one.400
https://problems.tourfold.com/document-management/invalid-move-targetInvalid move targetThe target folder for a document move is not allowed (missing or a managed_branch structural folder). The reason is surfaced in data.reason.422
https://problems.tourfold.com/document-management/must-be-soft-deleted-firstMust be soft-deleted firstThe document must be soft-deleted (moved to the user's Trash) before it can be permanently deleted (hard-deleted).409
https://problems.tourfold.com/document-management/cannot-modify-managed-folderCannot modify managed folderThis folder is managed by the system (object root or system root) and cannot be renamed, moved, or deleted.403
https://problems.tourfold.com/document-management/cannot-modify-soft-deleted-documentCannot modify soft-deleted documentThe document is soft-deleted (in the user's Trash) and read-only. Only restore and hard-delete are allowed; rename, description, move, tag, star, new-version upload, and AI analyze are rejected with this type. Folders are never soft-deleted in the new model so there is no folder counterpart.409
https://problems.tourfold.com/document-management/document-not-foundDocument not foundThe referenced document does not exist or is soft-deleted.404
https://problems.tourfold.com/document-management/version-not-foundDocument version not foundThe referenced document version does not exist, belongs to a different document, or has not been finalized yet.404
https://problems.tourfold.com/document-management/version-mime-mismatchVersion MIME mismatchA new version must use the same MIME type as the existing document. Expected and actual types are surfaced in data.expected and data.actual.422
https://problems.tourfold.com/document-management/invalid-download-renditionUnsupported download renditionThe rendition query parameter must be one of the supported aliases. Allowed values are surfaced in data.allowed; the rejected value is in data.value.422
https://problems.tourfold.com/document-management/upload-initiate-failedUpload initiate failedThe upload could not be initiated. The cause (filestore validation rejected the MIME or size, or another filestore error) is in data.cause and the response sub-problems.422
https://problems.tourfold.com/document-management/upload-finalize-failedUpload finalize failedThe upload could not be finalized. The cause (missing storage key, no pending version, or a filestore error) is included in the response sub-problems.422
https://problems.tourfold.com/document-management/extraction-not-foundExtraction not foundThe referenced extraction does not exist, or it does not belong to a document-management document.404
https://problems.tourfold.com/document-management/invalid-retention-daysInvalid retention daysThe document-management auto-hard-delete retention value is outside the allowed range. The rejected value and bounds are surfaced in data.value, data.min, and data.max.422

Task Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/tasks/definition-in-useTask definition in useTasks, including completed Tasks, or stored configuration use this definition. Structural changes and deletion are blocked; labels and permitted optional additions remain editable.409
https://problems.tourfold.com/tasks/required-target-in-useRequired Task relationship in useA Task requires the selected Object or Vehicle record, or authored Task inputs in a template or retained Workflow require the selected relationship, Tag, Skill or tracked-location source. Deletion is blocked while any required reference remains, including completed Task history.409
https://problems.tourfold.com/tasks/interaction-human-requiredTask interaction requires an active humanThe authenticated caller cannot answer Task interactions because it is not an active human user. API-only users and service accounts cannot answer. data.reason is not_member; additional grants do not satisfy this requirement.403

Comments Errors​

Returned by the polymorphic comments API under /api/v2/comments. Body-validation errors carry sub-problems pointing at the offending JSON pointer (#/body_markdown, #/edit_reason, etc.).

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/comments/target-not-foundTarget not foundThe supplied target_type / target_id does not resolve to an existing object the caller can see. Reserved for the Phase 5 ACL-inheritance check; not currently thrown.404
https://problems.tourfold.com/comments/parent-comment-not-foundParent comment not foundThe supplied parent_comment_id does not resolve to an existing comment.404
https://problems.tourfold.com/comments/parent-target-mismatchParent comment is on a different targetThe supplied parent_comment_id belongs to a different (target_type, target_id) than the new comment.422
https://problems.tourfold.com/comments/body-too-longComment body too longbody_markdown exceeds the configured maximum length. The cap is surfaced in data.max_length.422
https://problems.tourfold.com/comments/body-invalid-markdownComment body contains disallowed markdownbody_markdown contains constructs that are not on the comments allow-list (headings, raw HTML, images, non-http(s) link schemes, etc.). The offending constructs are listed as sub-problems with line_number pointers when available.422
https://problems.tourfold.com/comments/comment-not-foundComment not foundThe referenced comment does not exist (or has been hard-deleted).404
https://problems.tourfold.com/comments/cannot-edit-othersCannot edit another user's commentEditing a comment authored by another user requires the comments:update grant.403
https://problems.tourfold.com/comments/cannot-delete-othersCannot delete another user's commentDeleting a comment authored by another user requires the comments:delete grant.403
https://problems.tourfold.com/comments/moderation-reason-requiredModeration edit requires a reasonEditing another user's comment under the comments:update grant requires a non-blank edit_reason.422
https://problems.tourfold.com/comments/cannot-restore-not-deletedComment is not soft-deletedOnly soft-deleted comments can be restored; the referenced comment is currently live.422
https://problems.tourfold.com/comments/read-cursor-target-mismatchComment does not belong to the supplied targetcomment_id in mark-read-until does not belong to the supplied (target_type, target_id).422
https://problems.tourfold.com/comments/mention-type-unknownUnknown mention typeA mention token uses a type prefix the server does not understand.422
https://problems.tourfold.com/comments/mention-target-not-foundMention target not foundNo mention target matches the supplied (type, id) in the current tenant.404
https://problems.tourfold.com/comments/reaction-on-deleted-commentCannot react to a deleted commentThe referenced comment is soft-deleted; reactions can only be added to live comments.422
https://problems.tourfold.com/comments/reaction-not-foundReaction not foundDELETE /api/v2/comments/{id}/reactions/{reaction_id} was called with an id that does not exist or that belongs to a different user. Returned identically in both cases so the surface does not leak the existence of other users' reaction rows.404
https://problems.tourfold.com/comments/attachment-mime-not-allowedAttachment MIME type is not allowedThe uploaded file's MIME is on the comments attachment denylist (e.g. image/svg+xml, executable formats). The rejected MIME and the full denylist are surfaced in data.mime_type / data.blocked_mime_types.422
https://problems.tourfold.com/comments/attachment-too-largeAttachment exceeds per-file size limitThe uploaded file exceeds comments.attachments.max-bytes-per-file. The requested and maximum sizes are surfaced in data.requested_bytes / data.max_bytes.422
https://problems.tourfold.com/comments/attachment-storage-limit-exceededTenant storage allowance exceededThe upload would push the tenant past its storage allowance. The underlying billing problem type and quantities are surfaced in data.underlying_problem_type / data.underlying_data.422
https://problems.tourfold.com/comments/attachment-not-foundComment attachment not foundThe referenced attachment_id does not exist, has been hard-deleted, or has no original rendition.404
https://problems.tourfold.com/comments/attachment-blob-goneAttachment blob has been removedGET /api/v2/comments/attachments/{attachment_id}/download-url was called for an attachment whose underlying blob has been hard-deleted (target cascade, manual purge, orphan-cleanup gap). The attachment still appears on the comment with is_deleted=true; only the presigned-URL refresh surface returns 410.410
https://problems.tourfold.com/comments/attachment-not-from-commentsAttachment was uploaded for a different featureThe referenced file's source_key is not COMMENT_ATTACHMENTS β€” cross-feature blob reuse is rejected. The actual source key is surfaced in data.source_key.422
https://problems.tourfold.com/comments/attachment-upload-incompleteAttachment upload not yet completedThe referenced file exists but its original rendition is not in UPLOADED status. The current status is surfaced in data.upload_status.422
https://problems.tourfold.com/comments/attachment-mime-not-inline-previewableAttachment cannot be referenced inlineA ![alt](attachment:<uuid>) body reference targets a file whose MIME is not on the inline-previewable list (e.g. PDF cannot be embedded as <img>). Attach as a chip instead. The MIME is surfaced in data.mime_type.422
https://problems.tourfold.com/comments/attachment-inline-not-linkedInline reference not present in attachment listThe comment body references attachment:<uuid> for a file that is not in the request's attachment_ids array. The first unreferenced id is in data.attachment_id; the full set is in data.all_unlinked_attachment_ids.422
https://problems.tourfold.com/comments/attachment-inline-invalid-uriMalformed attachment: reference in bodyAn image destination uses the attachment: scheme but the suffix is not a valid UUID.422
https://problems.tourfold.com/comments/too-many-attachmentsComment exceeds attachment count limitThe request carries more than comments.attachments.max-per-comment files. The cap and the requested count are surfaced in data.max_per_comment / data.requested.422
https://problems.tourfold.com/comments/attachment-already-linkedAttachment is linked to a posted commentDELETE /api/v2/comments/attachments/uploads/{attachment_id} was called for an attachment already linked to a comment. The proper removal path is the comment update/delete endpoint, which cascades the underlying blob through the existing hard-delete hook.409

Notifications Errors​

Returned by the notification inbox under /frontend/v2/notifications and by NotificationEmitter.emit(...) calls from other features. invalid-action-url is enforced server-side both when an operator authors a system notification in the admin app and when a feature emits an in-app notification, so a malformed or non-https:// link cannot reach the client renderer.

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/notifications/notification-not-foundNotification not foundThe referenced notification does not exist, has expired, or does not belong to the caller. Returned identically for "no such id", "expired", and "belongs to another user" so the surface does not leak the existence of other users' rows.404
https://problems.tourfold.com/notifications/invalid-action-urlNotification action URL is not allowedaction_url must be a relative path starting with / or an absolute https:// URL. Other schemes (javascript:, data:, vbscript:, file:), scheme-relative URLs (//evil.com/x), and malformed URIs are rejected. The offending value is surfaced in data.action_url.422

Custom Domains Errors​

Returned by the workspace custom-domains API under /frontend/v2/custom-domains. The verify endpoint runs the TXT + CNAME DNS checks and returns this problem type on any DNS-side mismatch. Per-record details (which record failed, the expected value, the actually-resolved CNAME targets) live in the errors[] array as sub-problems with errorType slugs custom-domain-txt-record-missing and custom-domain-cname-record-mismatch (sub-problems aren't standalone ProblemType enums β€” they carry the same RFC 9457 shape but are scoped to the parent verification-failed problem). The frontend matches on the sub-problem type URI to colour the failing card.

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/custom-domains/verification-failedCustom domain verification failedDNS records required to verify the custom domain are missing or incorrect. errors[] contains per-record sub-problems (custom-domain-txt-record-missing and/or custom-domain-cname-record-mismatch) with the expected values in data.expected_record_name / data.expected_record_value / data.expected_record_target and, for CNAME, the actually-resolved targets in data.actual_targets. The row is still persisted with status = VERIFICATION_FAILED and the latest last_verification_error.422

Audit Log Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/audit-logs/invalid-time-rangeInvalid time rangeThe 'from' time must be before the 'to' time422
https://problems.tourfold.com/audit-logs/invalid-sortInvalid sort parameterSorting field or direction is not supported422

Device Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/devices/registered-to-another-workspaceDevice registered to another workspaceThis device id is already registered to another workspace409
https://problems.tourfold.com/devices/device-disabledDevice disabledThis device is disabled and cannot receive telemetry403
https://problems.tourfold.com/devices/keycloak-enrollment-requiredDevice enrollment requiredThis device must enroll into Keycloak before it can authenticate.401
https://problems.tourfold.com/devices/enrollment-challenge-invalidEnrollment challenge invalidThe enrollment challenge is invalid, expired, or already used. Request a fresh challenge and retry.422
https://problems.tourfold.com/devices/setup-link-unsupported-kindSetup link not supported for this device kindSetup links are only supported for Tourfold App devices.422
https://problems.tourfold.com/devices/setup-link-requires-admin-managed-devicesAdmin-managed device fleet requiredSetup links can only be sent for workspaces whose device fleet is admin-managed.422
https://problems.tourfold.com/devices/self-enrollment-not-allowedSelf-enrollment not allowedThis workspace provisions devices through admin setup links; a device cannot enroll itself.422
https://problems.tourfold.com/devices/current-user-association-requiredCurrent human login requiredValid human and Device proof do not match the registered session required by the command. Register the login before retrying.409
https://problems.tourfold.com/devices/user-association-changedUser association changedThe Device has a newer human login. Retain the originally observed episode when retrying logout.409
https://problems.tourfold.com/devices/vehicle-association-changedVehicle association changedThe Device’s Vehicle association no longer matches the observed episode. Refresh the context before a new decision.409
https://problems.tourfold.com/devices/device-token-requiredDevice token requiredRequired secondary proof is absent (device_proof_missing), or a Device-only operation received a human primary token (wrong_actor_type).403
https://problems.tourfold.com/devices/device-token-invalidDevice token invalidSecondary proof is unusable (device_proof_invalid), belongs to another workspace (tenant_scope), or authenticates a non-Device principal/unsupported kind (wrong_actor_type).403
https://problems.tourfold.com/devices/device-has-active-tourDevice has active tourDevice is associated with a vehicle that currently has an active tour422

Document Analyzer Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/document-analyzer/schema-invalidSchema is not validThe supplied schema could not be parsed as a JSON Schema (Draft 2020-12).422
https://problems.tourfold.com/document-analyzer/url-not-httpsURL must use HTTPSThe document URL must use HTTPS.422
https://problems.tourfold.com/document-analyzer/url-host-not-allowedURL host is not allowedThe document URL host is not in the configured allow-list. Submit a URL pointing at an allowed host (typically a presigned filestore URL).422
https://problems.tourfold.com/document-analyzer/unsupported-media-typeMedia type not supportedThe declared media type is not supported by the document analyzer.422
https://problems.tourfold.com/document-analyzer/url-fetch-failedCould not fetch document URLThe document URL could not be fetched.422
https://problems.tourfold.com/document-analyzer/document-too-largeDocument is too largeThe fetched document exceeded the maximum size allowed by the document analyzer.422
https://problems.tourfold.com/document-analyzer/media-type-mismatchDocument content does not match declared media typeThe declared media type does not match the actual document content.422
https://problems.tourfold.com/document-analyzer/model-output-does-not-match-schemaModel output did not match the schemaThe model could not produce a response that conforms to the supplied or inferred JSON Schema.422
https://problems.tourfold.com/document-analyzer/schema-inference-failedCould not infer a valid schema from the documentThe model could not produce a valid JSON Schema (Draft 2020-12) for the document. Submit again with an explicit schema.422
https://problems.tourfold.com/document-analyzer/provider-unavailableModel provider is unavailableThe upstream model provider is unavailable. Retry the job; if the failure persists, contact support.503

Geocoding Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/geocoding/no-resultsNo resultsGeocoding returned no results404

Skill Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/skills/managedManaged skillSystem and plugin skills (managed_by is system or plugin) cannot be renamed, given another short key, or deleted.409
https://problems.tourfold.com/skills/not-foundSkill not foundSkill was not found404

SMS Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/sms/gateway-rejectedSMS gateway rejected the messageThe provider refused a test message: rejected credentials, an invalid recipient or sender, or a 4xx answer from a custom endpoint. Fix the gateway configuration; retrying unchanged fails again. data.tracking_id references the FAILED SMS report entry and data.provider_status the provider's status code when available.422
https://problems.tourfold.com/sms/gateway-unavailableSMS gateway unavailableThe provider could not be reached or answered with a temporary failure (timeout, 5xx, 429) while sending a test message. Retry later. data.tracking_id references the FAILED SMS report entry.503

Saved List View Column Error Types​

These appear as errorType values inside the errors array of a validation-failed problem when a saved list view is created or updated. The field of each entry is the offending column's field path. Validation walks nested not / and / or branches, so one response reports every offending filter rather than only the first.

Error TypeDescription
unresolved-relationA relation slug in the column's dot-separated field path does not resolve from the root definition
definition-mismatchThe field path ends in a definition UUID that is not the definition reached at the end of the relation chain
invalid-filter-operatorThe filter operator is not one of the supported GraphQL filter operators
missing-filter-operatorThe filter sets no op and no not filter to negate
invalid-filter-negationA filter without op only negates its not filter and must not set value, relative_value, and or or
missing-filter-valueThe filter sets neither value nor relative_value
ambiguous-filter-valueThe filter sets both value and relative_value; they are mutually exclusive
unsupported-relative-filter-operatorrelative_value was used with an operator that cannot compare instants. Supported: _eq, _gt, _lt, _gte, _lte
invalid-relative-time-expressionrelative_value does not parse as a relative time expression. See the relative time syntax

Board layout errors use the same envelope. Their pointer is the offending column's group_by flag (#/columns/<index>/group_by) or, when no usable grouping column exists, #/layout.

Error TypeDescription
invalid-group-by-attributegroup_by is set on a column whose field is not a state attribute or a single-value select attribute of the root definition
duplicate-group-byMore than one column sets group_by; a view groups by at most one attribute
missing-group-bylayout is BOARD but no column sets group_by to a usable attribute (in the submitted columns, or among the stored columns)

Board settings (board) report the standard field problems listed above:

  • #/board/column_order/<index>:
    • field-type-invalid when the entry is neither a choice id nor none;
    • not-unique when a column is listed twice.
  • #/board/column_order: field-size-invalid for more than 100 entries.
  • #/board/column_width: field-too-small / field-too-large outside 200–600 pixels.

Tag Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/tags/not-foundTag not foundTag with the given id was not found404
https://problems.tourfold.com/tags/tag-already-associatedTag already associatedThis tag is already associated with the given resource409

Template Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/templates/not-foundTemplate not foundTemplate was not found404
https://problems.tourfold.com/templates/rendering-errorRendering errorError rendering PDF template500
https://problems.tourfold.com/templates/todo-not-foundTodo template not foundTodo template was not found404

Tenant Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/tenants/not-foundTenant not foundTenant was not found404
https://problems.tourfold.com/tenants/template-name-invalidInvalid template nameTemplate name must start with 'template_'422
https://problems.tourfold.com/tenants/source-tenant-is-frozenSource tenant is frozenCannot clone a frozen template tenant as a new template422
https://problems.tourfold.com/tenants/realm-mode-migration-not-allowedRealm-mode migration not allowedOnly the SHARED β†’ DEDICATED realm-mode migration is supported.422

Tenant Reset Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/tenant-reset/reset-not-allowedReset not allowedThis workspace cannot be reset. Ask an administrator to enable resets first403
https://problems.tourfold.com/tenant-reset/active-tours-presentActive tours in progressThis workspace has tours in progress. Finish or cancel them before resetting409
https://problems.tourfold.com/tenant-reset/no-pending-reset-requestNo pending reset requestThere is no pending reset to confirm. Request a confirmation code first404
https://problems.tourfold.com/tenant-reset/invalid-confirmation-codeInvalid confirmation codeThe confirmation code provided is not valid422
https://problems.tourfold.com/tenant-reset/confirmation-code-expiredConfirmation code expiredThe confirmation code has expired. Please request a new one422
https://problems.tourfold.com/tenant-reset/template-not-activeTemplate not activeThe selected template is not available. Choose one of the active templates422
https://problems.tourfold.com/tenant-reset/confirmation-email-rate-limitedConfirmation email rate limitedPlease wait before requesting another confirmation code429
https://problems.tourfold.com/tenant-reset/owner-email-unavailableOwner email unavailableThe workspace owner has no email address on file to send the confirmation code to422
https://problems.tourfold.com/tenant-reset/reset-failedReset failedThe workspace could not be reset. Your confirmation code is still valid β€” please try again500

Tenant Template Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/tenant-templates/template-not-foundTemplate not foundThe requested tenant template does not exist404
https://problems.tourfold.com/tenant-templates/tenant-not-frozenTenant is not a frozen templateThe tenantid_to_clone must reference a frozen tenant (name starts with 'template')422

Tour Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/tours/tour-endedTour endedThe tour has already ended422
https://problems.tourfold.com/tours/no-user-associatedNo user associatedNo user is associated with this tour422
https://problems.tourfold.com/tours/start-time-after-endStart time after endStart time must be before scheduled end422
https://problems.tourfold.com/tours/tour-has-unfinished-activitiesTour has unfinished activitiesCannot finish tour with activities in PENDING or STARTED status409
https://problems.tourfold.com/tours/tour-template-in-useTour template in useA current workflow draft or publication references this template. Remove those references and publish replacement versions before deleting it. Paused workflows also block deletion; data.target_id identifies the template.409
https://problems.tourfold.com/tours/template-needs-configurationTour template needs configurationRepair the template before creating a Tour from it; data.tour_template_id identifies the template with unresolved required inputs.409

Generic Task Tours​

Type URITitleRecoveryHTTP Status
https://problems.tourfold.com/tours/default-template-protectedDefault Tour template is protectedEdit the protected Default in place; it cannot be deleted or lose its Default identity. Attempts to write the read-only is_default field remain field-level 422 validation errors.409
https://problems.tourfold.com/tours/vehicle-use-conflictTour Vehicle use has changedThe replacement target is no longer assigned, or a Start replay differs from the current Vehicle/source state. Reread the Tour and explicitly use the active-Tour Vehicle command for a new intent.409
https://problems.tourfold.com/tours/device-activeDevice conflicts with active Tour workA login or Device assignment would conflict with the user's ongoing Tour. Choose a matching Vehicle/Device or resolve the active work first.409
https://problems.tourfold.com/vehicle-device-associations/mode-unconfirmedDevice association mode is unconfirmedAn authorized manager must confirm whether the Device is fixed to a Vehicle or portable before an action that depends on its mode.409
https://problems.tourfold.com/tours/execution-forbiddenTour execution is not permittedJoin the Tour as an active human participant; data.reason is not_member.403
https://problems.tourfold.com/tours/human-requiredActive human requiredUse an active human account; additional grants cannot resolve this restriction.403
https://problems.tourfold.com/tours/not-publishedTour is not publishedPublish before executing.409
https://problems.tourfold.com/tours/not-startedTour has not startedStart before finishing.409
https://problems.tourfold.com/tours/finishedTour is finishedThe Tour and its assigned work are immutable.409
https://problems.tourfold.com/tours/already-startedTour has startedDeletion, participant changes and planned-start changes are forbidden.409
https://problems.tourfold.com/tours/unfinished-workTour has unfinished workComplete or unassign Tasks and standalone Stops before finishing.409
https://problems.tourfold.com/tours/vehicle-activeVehicle is in useResolve the Vehicle’s active use before starting or changing this Tour.409
https://problems.tourfold.com/tours/vehicle-requiredVehicle requiredFirst Start requires an eligible assigned Vehicle because the Tour requires the system Vehicle skill. Select a Vehicle and retry Start.409
https://problems.tourfold.com/tours/vehicle-ineligibleVehicle ineligibleAn assigned Vehicle definition is excluded from Tours. Replace or remove the assignment, or change the exclusion before first Start.409
https://problems.tourfold.com/tours/vehicle-confirmation-requiredConfirm planned Vehicle assignmentExplicit confirmation is required to plan a Vehicle that is currently in use. data.active_use_conflicts supplies each conflicting Vehicle ID. Set acknowledge_active_use: true on that selection to confirm planned assignment; Start checks active use again.409
https://problems.tourfold.com/tours/participant-activeParticipant is already activeFinish the blocking Tour identified by data.tour_id or choose another participant.409
https://problems.tourfold.com/tours/participants-requiredParticipants requiredSelect participants before publication.409
https://problems.tourfold.com/tours/capacity-exceededTour capacity exceededAt most 500 Stops and 10000 Tasks plus Stops; reduce membership or select another Tour.409
https://problems.tourfold.com/tours/task-already-assignedTask already assignedMove or remove its existing assignment.409
https://problems.tourfold.com/tours/membership-changedMembership changedReread and submit the complete current order.409
https://problems.tourfold.com/tours/stop-has-tasksStop has assigned TasksUnassign its Tasks before deleting the Stop.409
https://problems.tourfold.com/tours/task-backed-stopTask completion controls StopComplete assigned Tasks rather than directly setting the Stop status.409
https://problems.tourfold.com/tours/same-stopDistinct Stops requiredChoose different source and destination Stop IDs.409

Role Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/roles/system-role-immutableSystem role is immutableSystem roles cannot be updated or deleted.409
https://problems.tourfold.com/roles/grant-assignment-deniedGrant assignment deniedAdding grants the caller cannot manage, or modifying assignable_by_roles on a role whose transitive editable grants exceed the caller's grants, is forbidden. data.reason is missing_grant; data.required_grants lists the rejected grants. Existing unmanageable grants are preserved on update.403
https://problems.tourfold.com/roles/role-assignability-update-deniedRole assignability update deniedModifying assignable_by_roles is forbidden when the caller cannot currently assign the target role. data.reason is not_member (matching users/role-assignment-denied) because the caller is not a member of any role allowed to assign the target role; data.role_id and data.role_name identify the role.403

A reserved role name returns top-level validation-failed (422), with errors[].type equal to https://problems.tourfold.com/roles/reserved-role-name and pointer #/name.

User Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/users/already-assignedUser already assignedUser is already assigned422
https://problems.tourfold.com/users/cannot-delete-selfCannot delete yourselfUsers cannot delete themselves. Carries data.reason: self_target and data.user_id.403
https://problems.tourfold.com/users/cannot-activate-selfCannot activate yourselfUsers cannot activate themselves. Carries data.reason: self_target and data.user_id.403
https://problems.tourfold.com/users/cannot-deactivate-selfCannot deactivate yourselfUsers cannot deactivate themselves. Carries data.reason: self_target and data.user_id.403
https://problems.tourfold.com/users/owner-deletion-conflictOwner deletion conflictTransfer workspace ownership before deleting this user. Carries data.user_id; additional grants do not resolve the conflict.409
https://problems.tourfold.com/users/not-tenant-ownerNot the workspace ownerOnly the current workspace owner can perform this action β€” e.g. transferring ownership. Distinct from access-denied because it is terminal: no grant can make a non-owner the owner, so do not prompt the user to request permissions. Carries data.reason: not_owner.403
https://problems.tourfold.com/users/cannot-change-own-rolesCannot change own rolesChanging your own role assignments is forbidden; data.reason is self_target.403
https://problems.tourfold.com/users/role-assignment-deniedRole assignment deniedThe caller cannot assign this role; data.reason is not_member.403
https://problems.tourfold.com/users/owner-role-change-conflictOwner role change conflictUse the ownership-transfer action to change the owner; ordinary user creation or role updates cannot assign or remove the owner role.409
https://problems.tourfold.com/users/profile-self-managedProfile managed by the userPeople in this workspace manage their own firstname, lastname and phone_number (is_profile_self_managed: true), because they share them across workspaces. A user update that changes them for another user is rejected (sending the current values is accepted), and so is a user creation that carries any of them: invite by email only. Carries data.fields (the rejected field names) and, on an update, data.user_id. No grant resolves it.422

Vehicle Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/vehicles/no-active-device-associationNo active device associationNo active vehicle device association found422
https://problems.tourfold.com/vehicles/no-device-associationNo device associationNo vehicle device association found422
https://problems.tourfold.com/vehicles/vehicle-already-assignedVehicle already assignedVehicle is already assigned422
https://problems.tourfold.com/vehicles/vehicle-has-active-tourVehicle has active tourVehicle currently has an active tour422
https://problems.tourfold.com/vehicles/vehicle-not-associatedVehicle not associatedVehicle is not associated422

Vehicle Provider Connection Errors​

Type URITitleRecoveryHTTP Status
https://problems.tourfold.com/vehicle-provider-connections/account-disabledProvider account is disabledEnable the provider account before asking the provider through it.409
https://problems.tourfold.com/vehicle-provider-connections/authorization-already-requestedAuthorization already requestedConsent is already pending or approved; refresh it to learn whether that changed.409
https://problems.tourfold.com/vehicle-provider-connections/connection-endedProvider connection has endedNothing more can be asked of the provider through an ended connection; connect the Vehicle again.409
https://problems.tourfold.com/vehicle-provider-connections/operation-in-progressProvider operation in progressWait until the connection's open operation of the same kind settles, then ask again.409
https://problems.tourfold.com/vehicle-provider-connections/request-id-reusedRequest id reusedThe request_id was used for a different request of the same kind on this connection; send the original request or a new request_id.409

Objects and Records Errors​

The Objects and Records API uses generic problem types (not-found, invalid-input, validation-failed, unknown-error) at the top level. The specific error context is conveyed through field validation error types in the errors array of the response body.

Top-Level Problem Types​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/not-foundNot foundObject, record, attribute, option, state, or relationship was not found404
https://problems.tourfold.com/invalid-inputInvalid inputThe request body could not be parsed (e.g., malformed or unparseable JSON)400
https://problems.tourfold.com/validation-failedValidation failedObject, attribute, record, query, or permission validation failed422
https://problems.tourfold.com/resource-conflictResource conflictThe supplied lock_version is stale409
https://problems.tourfold.com/objects/object-definition-in-useObject definition in useA current workflow draft or publication references this definition. Remove those references and publish replacement versions before deleting it. Paused workflows also block deletion; data.target_id identifies the definition.409
https://problems.tourfold.com/objects/object-attribute-in-useObject attribute in useA current workflow draft or publication references an attribute being removed or replaced. Remove those references and publish replacement versions first. Paused workflows also block deletion; data.target_id identifies the attribute and data.object_id its object.409
https://problems.tourfold.com/objects/relationship-target-in-useRelationship target in useThe object is targeted by relationship attributes owned by other objects; data.blocking_relationships identifies them409
https://problems.tourfold.com/objects/count-unit-target-in-useCount unit target in useCapacity attributes of other definitions count this object as their unit (unit_kind: object). Retarget or remove them before deleting it; data.target_id identifies the object, data.reference_count and data.references[] the counting attributes (first 20).409
https://problems.tourfold.com/payload-too-largePayload too largeRequest payload exceeds the maximum allowed size413
https://problems.tourfold.com/records/query-timeoutRecord query timed outA structured REST record query exceeded its execution deadline; data.timeout_ms carries the configured limit503
https://problems.tourfold.com/unknown-errorUnknown errorAn unexpected error occurred (e.g., DDL change failure)500

Typed Object and Attribute Validation​

Clients create typed objects and attributes; the public API does not accept raw JSON Schema, imperative relation resources, or a separate association payload. Common field error types are:

Error TypeDescription and pointer
field-requiredA required input is missing; points to that field, for example #/attributes/0/config/target.
unknown-fieldAn unknown config member was sent; points to the exact member. Retired relationship fields such as allowed_objects are rejected this way.
inapplicable-fieldA known config member does not apply to the selected attribute type.
invalid-enum-valueAn enum-like input such as unit_kind has an unsupported value.
invalid-slug / slug-already-exists / slug-reserved / duplicate-attribute-slugThe object or attribute slug is invalid, duplicated, or reserved.
attribute-type-required / attribute-type-invalidAttribute type is missing or unsupported.
attribute-config-missingThe selected type requires config.
unique-unsupported-type / unique-immutableUniqueness is unsupported for this type or cannot be changed after creation.
index-unsupported-typeThe attribute type cannot carry an index; raw_json documents are never indexed.
display-template-unknown-attributedisplay_template refers to an attribute that does not exist.
unsupported-display-template-attributedisplay_template refers to an attribute whose value has no label, such as a raw_json document.
raw-json-too-large / raw-json-too-deep / raw-json-too-many-itemsA raw_json value or default exceeds the platform size, nesting, or item limits; the pointer names the offending member, for example #/data/payload/items.
rich-text-unsupported-element / rich-text-unsupported-attribute / rich-text-unsafe-linkA rich_text value or default uses markup outside the supported subset, an attribute other than a link href, or a link scheme other than http, https, mailto, tel. data.element and data.attribute name the offender.
rich-text-too-large / rich-text-too-deepA rich_text value or default exceeds the canonical size or nesting limit.
full-name-component-requiredA full_name value carries a title without a first_name or last_name.
links-unsafe-linkA links URL uses a scheme other than http, https, mailto or tel; the pointer names the link's url.
links-primary-requiredA links value has alternatives but no primary link.
invalid-iconicon is not an icon key: use up to 64 lowercase letters, digits and single hyphens. Points to #/icon.
invalid-pattern / unacceptable-patternA text pattern is invalid or uses unsupported non-linear-time features.
relationship-target-not-foundSingular config.target does not resolve to an object.
relationship-reverse-slug-conflictreverse.slug is already used by an owned attribute or relationship on the target object; points to the offending reverse slug.
relationship-reverse-unsupportedThe relationship target does not accept a managed reverse attribute, for example the system user object; points to config.reverse.
relationship-reverse-managedA client tried to send, update, or delete a server-managed B-side reverse. The error data identifies owner_object and owner_attribute.
system-property-updated / system-property-deletedA built-in system attribute was changed or omitted.

An object-level structural protection failure is a top-level validation-failed response (422). System/built-in objects expose their mutability in the object response; clients must not infer it from internal JSON-Schema flags.

Relationship Record Error Types​

Error TypeDescription
required-relationA required relationship value is missing.
cardinality-violation-sourceThe source-side cardinality would be exceeded.
cardinality-violation-targetThe target-side cardinality would be exceeded.
object-not-foundA relationship record id does not exist in its configured target object.
invalid-reference-valueA tag/skill id or label cannot be resolved; points to the exact array element under #/data.

Relationship Query and Traversal Problems​

These namespaced problem types are raised by the relationship query engine. In GraphQL responses the same URI appears in extensions.code; REST problem responses use it as type.

Type URIDescription
https://problems.tourfold.com/relation/unknown-field-in-order-byorder_by names a field that is not present on the selected object.
https://problems.tourfold.com/relation/invalid-sort-directionThe requested sort direction is not supported.

URL, Query, and Include Validation​

These validation failures also return field pointers even though the input is not in the JSON body:

Error TypePointer
unknown-query-parameter#/<parameter_name>
unknown-relationship-attribute#/include
invalid sort field/direction#/sort
non-unique or unknown business-key attribute#/attribute_ref
missing or blank business-key value#/attribute_value

Record Validation Error Types​

These appear when record data fails validation against the object schema.

Error TypeDescription
type-mismatchValue does not match the expected type
required-fieldA required field is missing
invalid-enum-valueValue is not one of the allowed enum values
invalid-const-valueValue does not match the expected constant
string-too-shortString length is below the minimum
string-too-longString length exceeds the maximum
pattern-mismatchString does not match the required pattern
value-too-smallNumeric value is below the minimum
value-too-largeNumeric value exceeds the maximum
not-multiple-ofNumeric value is not a multiple of the required value
too-few-itemsArray has fewer items than allowed
too-many-itemsArray has more items than allowed
duplicate-itemsArray contains duplicate items when uniqueness is required
invalid-formatValue does not match the required format
too-few-propertiesObject has fewer properties than required
too-many-propertiesObject has more properties than allowed
additional-properties-not-allowedObject contains properties not defined in the schema
oneOf-mismatchValue does not match exactly one of the oneOf schemas
anyOf-mismatchValue does not match any of the anyOf schemas
allOf-mismatchValue does not match all of the allOf schemas
not-mismatchValue matches a schema it should not
conditional-mismatchValue does not satisfy a conditional (if/then/else) schema
dependent-requiredA dependent required property is missing
dependent-schema-mismatchValue does not match a dependent schema
validation-errorGeneric validation error (fallback)
instance-payload-too-largedata payload exceeds the configured max size (HTTP 413). This legacy-stable sub-error name applies to record writes. Top-level type: payload-too-large.

Objects and Records Error Example​

{
"type": "https://problems.tourfold.com/validation-failed",
"title": "Validation failed",
"detail": "Attribute configuration validation failed",
"status": 422,
"errors": [
{
"type": "https://problems.tourfold.com/unknown-field",
"title": "Unknown field",
"detail": "Unknown attribute configuration field 'allowed_objects'",
"pointer": "#/attributes/0/config/allowed_objects"
}
]
}

Objects and Records GraphQL Errors​

These errors occur when using the Objects and Records GraphQL API endpoint.

GraphQL failures are returned in the errors array (typically with HTTP 200 OK) and do not use RFC 9457 problem payload fields.

Which errors carry a code​

Everything Tourfold rejects about a query carries a stable extensions.code β€” the limits below, a malformed cursor, contradictory pagination arguments, and every rejected filter operand. Branch on that code. The full list, with the data each one reports, is in GraphQL errors and limits.

Errors raised by the GraphQL engine itself use the stable https://problems.tourfold.com/graphql/invalid-query code. The original engine classification remains beside it as informational metadata:

Message patternMeaning
Validation error (FieldUndefined@...) ... Field ... is undefinedThe field is not in your workspace's generated schema. Check the schema endpoint.
Validation error (WrongType@...) ... not a valid SortDirectionAn order_by direction other than asc or desc.
Validation error (WrongType@...) ...An argument value of the wrong type for its declared input.
Invalid syntax ...The document does not parse.

Do not match the message patterns in this table. They illustrate when graphql/invalid-query is used; extensions.code is the contract.

Query Validation​

ConstraintLimitDescription
Query length10,000 charactersMaximum length of the GraphQL query string
Query cost100,000 estimated rowsMaximum rows a query may be estimated to materialise. A connection multiplies its subtree by its page size; plain fields cost 1. Exceeding it returns graphql/query-too-complex.
Query depth12 levelsMaximum nesting depth, counted in Relay levels rather than relation hops: a bare connection already costs 4, and each to-many hop adds 3. Exceeding it returns graphql/query-too-deep.
Execution time10 seconds wall-clockMaximum time spent executing one operation. Exceeding it returns graphql/query-timeout and interrupts cooperative work.
Page size (first/last)100Larger values return graphql/invalid-pagination with the supplied value and maximum.
Default page size20 (root), 10 (nested)Applied when neither first nor last is given. The nested default is smaller because a nested connection resolves once per parent row.
Filter nesting depth4Maximum where recursion depth (_and / _or). Independent of query depth.
Relationship order-by nesting1 to-one hopDeeper paths and to-many parent ordering are not expressible in the generated schema.

Query cost replaced an earlier "query complexity" score of 25, which counted fields and so was inversely correlated with actual cost β€” it rejected a wide table view while permitting a narrow, deeply paginated traversal orders of magnitude more expensive. A response reports its cost under extensions.cost whenever the request reached cost analysis β€” successful executions and query-too-complex refusals β€” so a query can be tuned before it starts being refused. Syntax and validation failures are caught earlier and carry no cost.

See GraphQL errors and limits for the worked cost arithmetic and how each limit is counted.

Objects and Records GraphQL Error Example​

{
"errors": [
{
"message": "Validation error (FieldUndefined@[vending_machine/cpu_processor]) : Field 'cpu_processor' in type 'vending_machine' is undefined",
"locations": [{ "line": 5, "column": 9 }],
"extensions": {
"code": "https://problems.tourfold.com/graphql/invalid-query",
"title": "Invalid GraphQL query",
"classification": "ValidationError"
}
}
]
}

The data key is absent because document validation prevented execution.

Billing Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/billing/billing-customer-missingBilling customer missingThe tenant has no Stripe customer yet, so this billing action is not available422
https://problems.tourfold.com/billing/plan-change-in-progressPlan change in progressA billing plan change is already in progress for this tenant409
https://problems.tourfold.com/billing/plan-change-not-allowedPlan change not allowedThe subscription plan cannot be changed in the current billing state422
https://problems.tourfold.com/billing/seat-cap-exceededSeat cap reachedThe tenant has reached the maximum number of paid seats allowed by its current plan422
https://problems.tourfold.com/billing/stripe-billing-unavailableStripe billing unavailableStripe billing could not be reached or could not process the request503
https://problems.tourfold.com/billing/plan-configuration-invalidPlan configuration invalidThe plan's Stripe configuration is incomplete or inconsistent and cannot be materialized (a server-side/config condition, not a client error).500

Signup Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/signup/email-not-verifiedEmail not verifiedVerify your email before continuing with the signup flow409
https://problems.tourfold.com/signup/invalid-verification-codeInvalid verification codeThe verification code is not valid, was used up by five wrong attempts, or no signup exists for the email; all answer alike422
https://problems.tourfold.com/signup/verification-code-expiredVerification code expiredThe verification code has expired; request a new one422
https://problems.tourfold.com/signup/subdomain-not-availableSubdomain not availableThe requested subdomain is already taken409
https://problems.tourfold.com/signup/subdomain-reservedSubdomain reservedThe requested subdomain is reserved and cannot be used409
https://problems.tourfold.com/signup/subdomain-invalid-formatInvalid subdomain formatSubdomain must use 3-16 lowercase alphanumeric characters422
https://problems.tourfold.com/signup/session-not-foundSession not foundThe signup session does not exist404
https://problems.tourfold.com/signup/session-already-completedSession already completedThe signup session has already been completed409
https://problems.tourfold.com/signup/session-not-readySession not readyComplete all required steps before finishing the signup422
https://problems.tourfold.com/signup/payment-pendingPayment pendingThe payment is still processing. Please wait and try again409
https://problems.tourfold.com/signup/completion-in-progressSignup completion in progressThe signup is already being completed. Please wait and try again409
https://problems.tourfold.com/signup/payment-not-completedPayment not completedThe payment has not completed409
https://problems.tourfold.com/signup/payment-failedPayment failedThe payment failed. Please choose a plan and try again409
https://problems.tourfold.com/signup/email-rate-limitedEmail rate limitedToo many verification requests in a short period429
https://problems.tourfold.com/signup/invalid-invite-codeInvalid invite codeThe invite code provided is not valid422
https://problems.tourfold.com/signup/email-sending-failedEmail sending failedThe verification email could not be sent503
https://problems.tourfold.com/signup/tenant-creation-failedTenant creation failedThe platform could not create a tenant for this signup500
https://problems.tourfold.com/signup/account-link-requiredAccount link requiredThe verified email already has a Tourfold account (account_state: EXISTING_ACCOUNT). Log in with it and link it (POST /frontend/v2/signup/{session_id}/account-link) before entering the account details or any later step. Also returned before checkout or completion when an account for the email was taken up since the email was verified; the session is back at ACCOUNT_DETAILS then.409
https://problems.tourfold.com/signup/account-link-rejectedAccount link rejectedThe access token does not prove the signup's account; nothing is linked. data.reason: token_rejected (not a valid, fresh access token of the signup client) or account_mismatch (the token belongs to another account than the signup's email). Log in again with the account of that email.403
https://problems.tourfold.com/signup/account-profile-incompleteAccount profile incompleteThe account has no first or last name, which the workspace owner needs. Complete the profile in the login and link again.422

Capacity Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/capacity/not-foundMeasure unit not foundMeasure unit was not found404
https://problems.tourfold.com/capacity/measure-unit-in-useMeasure unit in useObject, Task or Vehicle definition attributes still reference the unit (capacity with unit_kind: measure, or measure). Remove or retarget them before deleting it. data.target_id identifies the unit; data.reference_count and data.references[] (definition_id, definition_slug, resource_owner, attribute_id, attribute_slug, attribute_type) identify the referencing attributes (first 20).409

Custom plugin errors​

Custom plugin error types are described in the plugin’s API specification. Contact sales@tourfold.com for more information and customization.