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. Errors Tourfold raises carry the same Type URI in extensions.code that a REST error carries in type; errors raised by the GraphQL engine while parsing or validating a document carry no extensions.code at all. 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_author, not_member, plan_restricted, tenant_scope, resource_locked); grant-based denials also carry data.required_grants when the required grants are statically known.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 allowedThis action is not allowed403
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/illegal-argumentIllegal argumentAn illegal argument was provided422
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
}

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 — carry no extensions.code, because they are produced before any Tourfold code runs. Branch on extensions.code when it is present and fall back to message when it is not; never assume every entry in errors has a code.

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/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/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: the two limit errors give the measured value next to the limit, 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/invalid-tenant-public-idInvalid tenant public idThe tenant_public_id path token must be <tenantId>.<publicId> with both segments being valid UUIDs.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
https://problems.tourfold.com/usage/configuration-invalidUsage configuration invalidUsage metering is not configured correctly for this tenant or meter422

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

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

Case Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/cases/cases-activeCases activeCases are currently active422
https://problems.tourfold.com/cases/case-already-assignedCase already assignedThe case is already assigned422
https://problems.tourfold.com/cases/action-not-allowedAction not allowedThis action is not allowed on the case422
https://problems.tourfold.com/cases/confirmation-presentConfirmation presentCase confirmation is already present422
https://problems.tourfold.com/cases/case-finishedCase finishedThe case is finished422
https://problems.tourfold.com/cases/not-approvedCase not approvedThe case is not approved422
https://problems.tourfold.com/cases/oeamtc-missing-idMissing OEAMTC Case IDOEAMTC Case ID is missing422
https://problems.tourfold.com/cases/oeamtc-update-failedCannot update OEAMTC CaseFailed to update OEAMTC case422
https://problems.tourfold.com/cases/oeamtc-not-foundOEAMTC Case not foundOEAMTC Case was not found404

Device Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/device/platform-errorPlatform errorDevice platform error422
https://problems.tourfold.com/device/registered-to-another-workspaceDevice registered to another workspaceThis device id is already registered to another workspace409
https://problems.tourfold.com/device/device-disabledDevice disabledThis device is disabled and cannot receive telemetry403
https://problems.tourfold.com/device/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/job-not-foundJob not foundNo document analysis job with that id exists in the current tenant.404
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

Message Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/messages/acknowledged-by-field-emptyInvalid InputacknowledgedBy field can't be empty422

Skill Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/skills/not-foundSkill not foundSkill was not found404
https://problems.tourfold.com/skills/shortkey-not-foundShortkey not foundSkill shortkey not found404

SMS Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/sms/send-errorSMS send errorError sending SMS500

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/invalidTemplate invalidTemplate is not valid500
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 tenant_id_to_clone must reference a frozen tenant (name starts with 'template_')422

Todo Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/todos/not-foundTodo not foundTodo was not found404

Tour Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/tours/tour-endedTour endedThe tour has already ended422
https://problems.tourfold.com/tours/tour-not-accepting-casesTour not accepting casesThis tour is not accepting new cases422
https://problems.tourfold.com/tours/capacity-reachedCapacity reachedThe tour has reached its workload capacity422
https://problems.tourfold.com/tours/no-user-associatedNo user associatedNo user is associated with this tour422
https://problems.tourfold.com/tours/invalid-lea-toursInvalid LEA toursWrong number of LEA tours500
https://problems.tourfold.com/tours/cannot-duplicate-finishedCannot duplicate finishedCannot duplicate a finished tour500
https://problems.tourfold.com/tours/association-conflictAssociation conflictTour case association conflict409
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

User Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/users/password-errorPassword errorPassword could not be set422
https://problems.tourfold.com/users/already-assignedUser already assignedUser is already assigned422
https://problems.tourfold.com/users/token-not-validToken not validThe provided token is not valid422
https://problems.tourfold.com/users/tokens-not-foundTokens not foundNo tokens were found404
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

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
https://problems.tourfold.com/vehicles/vehicle-type-not-foundVehicle type not foundReferenced vehicle type does not exist422

Custom Objects Errors​

Custom Objects 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 foundDefinition, instance, or relation 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 failedSchema or instance validation failed422
https://problems.tourfold.com/payload-too-largePayload too largeRequest payload exceeds the maximum allowed size413
https://problems.tourfold.com/unknown-errorUnknown errorAn unexpected error occurred (e.g., DDL change failure)500

Definition-Level Protection​

When a PUT or DELETE is attempted on a protected definition, the request is rejected before schema validation runs. The error is a top-level validation-failed response (HTTP 422) — no errors array is present. The detail field distinguishes the two cases:

Scenariodetail value
Definition has readOnly: true (e.g. tour, case, activity)"The definition of '<slug>' is read only."
Definition has builtIn: true but is not read-only (e.g. location)"The definition of '<slug>' is a built-in definition and cannot be modified."

Definition & Schema Validation Error Types​

These appear as errorType values inside the errors array when a definition create or update request fails validation.

Error TypeDescription
title-requiredTitle is required for a definition
invalid-slugSlug format is invalid
slug-already-existsA definition with the same slug already exists
slug-reservedSlug is reserved for a built-in or read-only definition and cannot be reused
read-only-schemaA system property (e.g. id, created_at) on the definition has its readOnly flag removed or set to false, which is not permitted
invalid-schema-structureSchema violates JSON Schema 2020-12 meta-schema. In fallback parser/error paths, detail can be: Schema is incorrect and requires updating, please update the schema for slug '<slug>'
schema-too-deeply-nestedSchema has excessive nesting depth
definition-payload-too-largeschema payload exceeds the configured max size (HTTP 413). Top-level type: payload-too-large. Sub-error detail: Payload for 'schema' exceeds max size of {maxBytes} bytes (actual: {actualBytes} bytes)
validation-errorGeneric fallback for unexpected runtime errors during schema validation

Property Validation Error Types​

Error TypeDescription
invalid-property-typeProperty type is not a valid JSON Schema type
invalid-property-nameProperty name format is invalid
duplicate-property-nameDuplicate property name (case-insensitive)
property-slug-conflicts-with-relationProperty name conflicts with an existing relation slug
too-many-propertiesDefinition exceeds the maximum of 20 properties
invalid-default-valueDefault value does not match the property schema
default-value-requiredCannot add or make property required without a default value when existing instances contain null values
unsupported-keywordSchema uses a JSON Schema keyword that is not supported (e.g. patternProperties)
invalid-patternpattern value is not a syntactically valid regular expression
unacceptable-patternpattern value is syntactically valid but uses features that are not supported, such as lookaheads or backreferences. Only linear-time regular expressions are accepted

Property Rename Error Types​

Error TypeDescription
incompatible-type-changeInvalid property type conversion during rename
invalid-rename-fromrenameFrom is not allowed during definition creation
invalid-rename-from-referencerenameFrom references a non-existent property
invalid-rename-from-valuerenameFrom value has an invalid format
rename-conflictTarget property name already exists

Relation Error Types​

Error TypeDescription
definition-not-foundReferenced definition does not exist for the relation
duplicate-relation-slugRelation slug is already used on this definition
https://problems.tourfold.com/relation/relation-id-nullRelation has an id null
https://problems.tourfold.com/relation/unknown-field-in-order-byUnknown field in order by request
https://problems.tourfold.com/relation/unknown-nested-field-in-order-byUnknown nested field in order by request
https://problems.tourfold.com/relation/invalid-sort-directionInvalid sort direction
https://problems.tourfold.com/relation/nesting-depth-exceededNesting depth limit exceeded
relation-not-foundRelation was not found
required-relationA required relation is missing in the associations
location-relation-must-be-one-to-oneA relation marked with settings_type: "location" must have cardinality ONE on both sides. The offending side's actual cardinality is surfaced in data.actual. The error appears once per offending side and the pointer (#/relations/{N}/a/cardinality or .../b/cardinality) identifies which one.
location-relation-must-target-property-locationA relation marked with settings_type: "location" must connect to the built-in location definition on one side. Returned when neither side's definition_slug is location.

Location Error Types​

These errors come from the location built-in pre-processor when creating or updating a location instance.

Error TypeDescription
invalid-tracking-idtracking_id is not a syntactically valid UUID.
tracking-id-not-foundtracking_id does not reference an existing location instance. The reference must already be persisted; pointing at another instance being created in the same batch is rejected with this type.
geocoding-failedAddress geocoding returned no result for the supplied street / street_number / post_code / city / country.

Association Error Types​

Error TypeDescription
cardinality-violation-sourceSource cardinality constraint violated
cardinality-violation-targetTarget cardinality constraint violated
duplicate-associationDuplicate association for same relation and target
object-not-foundAssociated instance was not found

Instance Validation Error Types​

These appear when instance data fails validation against the definition 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). Top-level type: payload-too-large. Sub-error detail: Payload for 'data' exceeds max size of {maxBytes} bytes (actual: {actualBytes} bytes)

Custom Objects Error Example​

{
"type": "https://problems.tourfold.com/validation-failed",
"title": "Validation failed",
"detail": "Schema validation failed with 1 error(s)",
"status": 422,
"errors": [
{
"type": "default-value-required",
"title": "Default value required",
"detail": "Cannot add or make property 'priority' required without a default value because existing instances contain null values for this property",
"pointer": "#/priority"
}
]
}

Custom Objects GraphQL Errors​

These errors occur when using the Custom Objects 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.

Only errors raised by the GraphQL engine itself, before any Tourfold code runs, have no code. Those are document problems, and message plus locations is all there is:

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.
note

Earlier versions of this page listed message patterns for filter-depth, cursor and filter-operand failures. Those now carry stable codes and their wording has changed — match the code, not the text.

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.
Page size (first/last)100Larger values are silently capped.
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.
Order-by nesting depth3Maximum order-by nesting depth
JSON filter operand size3,000 charactersMaximum size of JSON values in filter operators
LIKE wildcards2Maximum number of wildcard characters in LIKE patterns

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.

Custom Objects GraphQL Error Example​

{
"data": null,
"errors": [
{
"message": "Validation error (WrongType@[product]) : argument 'order_by[0].price' with value 'EnumValue{name='invalid_direction'}' is not a valid 'SortDirection' - Literal value not in allowable values for enum 'SortDirection' - 'EnumValue{name='invalid_direction'}'",
"locations": [{ "line": 1, "column": 11 }],
"path": null
},
{
"message": "Validation error (FieldUndefined@[vending_machine/cpu_processor]) : Field 'cpu_processor' in type 'vending_machine' is undefined",
"locations": [{ "line": 5, "column": 9 }],
"path": null
},
{
"message": "Validation error (FieldUndefined@[vending_machine/manufacturer/founding_year]) : Field 'founding_year' in type 'manufacturer' is undefined",
"locations": [{ "line": 8, "column": 13 }],
"path": null
}
]
}

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-already-verifiedEmail already verifiedThis email address has already been verified409
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 provided is not valid422
https://problems.tourfold.com/signup/verification-code-expiredVerification code expiredThe verification code has expired422
https://problems.tourfold.com/signup/invalid-resume-tokenInvalid resume tokenThe resume token is not valid or has expired422
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

Capacity Errors​

Type URITitleDescriptionHTTP Status
https://problems.tourfold.com/capacity/not-foundMeasure unit not foundMeasure unit was not found404