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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/unknown-error | Unknown error | An unexpected error occurred | 500 |
https://problems.tourfold.com/invalid-input | Invalid input | The provided input was not valid | 400 |
https://problems.tourfold.com/business-rule-violation | Business rule violation | The request violates business rules | 422 |
https://problems.tourfold.com/not-found | Not found | The requested resource was not found | 404 |
https://problems.tourfold.com/method-not-allowed | Method not allowed | The 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-acceptable | Not acceptable | No representation of the resource matches the Accept header | 406 |
https://problems.tourfold.com/unsupported-media-type | Unsupported media type | The 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-required | Authentication required | Valid 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-denied | Access denied | You 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-deactivated | User deactivated | This 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-disabled | Tenant disabled | This tenant is disabled | 403 |
https://problems.tourfold.com/tenant-billing-locked | Tenant billing locked | This tenant is locked because billing requires attention | 402 |
https://problems.tourfold.com/action-not-allowed | Action not allowed | A 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-failed | Validation failed | One or more fields failed validation | 422 |
https://problems.tourfold.com/resource-conflict | Resource conflict | The request conflicts with the current state | 409 |
https://problems.tourfold.com/rate-limit-exceeded | Rate limit exceeded | Rate limit exceeded for this endpoint | 429 |
https://problems.tourfold.com/too-many-requests | Too many requests | Too many requests in the time window | 429 |
https://problems.tourfold.com/burst-limit-exceeded | Burst limit exceeded | Burst rate limit exceeded | 429 |
https://problems.tourfold.com/not-unique | Not unique | The provided details were not unique | 422 |
https://problems.tourfold.com/payload-too-large | Payload too large | The request payload exceeds the maximum allowed size | 413 |
https://problems.tourfold.com/not-implemented | Not implemented | This functionality is not implemented | 501 |
https://problems.tourfold.com/upstream-service-unavailable | Upstream service unavailable | An upstream service is temporarily unavailable | 503 |
https://problems.tourfold.com/login-failed | Login failed | Authentication 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-broken | Client connection broken | The client connection was interrupted | 500 |
https://problems.tourfold.com/empty-collection-argument | Empty collection argument | The provided collection argument must not be empty | 422 |
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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/definitions/schema-locked | Definition schema is locked | The 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 URI | Meaning |
|---|
https://problems.tourfold.com/field-validation-error | The field failed validation and no narrower standard type applies. |
https://problems.tourfold.com/field-required | The field is missing, null, empty, or blank. |
https://problems.tourfold.com/field-too-large | A numeric value is above its allowed maximum. |
https://problems.tourfold.com/field-too-small | A numeric value is below its allowed minimum. |
https://problems.tourfold.com/field-size-invalid | A string or collection length is outside its allowed bounds. |
https://problems.tourfold.com/field-type-invalid | The value has the wrong JSON type or shape. |
https://problems.tourfold.com/field-out-of-range | The value is outside the field's allowed range. |
https://problems.tourfold.com/invalid-email | The value is not a valid email address. |
https://problems.tourfold.com/invalid-phone-number | The value is not a valid international phone number. |
https://problems.tourfold.com/invalid-enum-value | The value is not one of the allowed enum members. |
https://problems.tourfold.com/not-unique | The 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 URI | Title | Description |
|---|
https://problems.tourfold.com/graphql/invalid-query | Invalid GraphQL query | The document could not be parsed or validated against the workspace schema |
https://problems.tourfold.com/graphql/query-too-deep | Query too deep | The query nests more levels than the configured maximum depth |
https://problems.tourfold.com/graphql/query-too-complex | Query too complex | The query is estimated to materialise more rows than the configured budget allows |
https://problems.tourfold.com/graphql/query-timeout | Query timed out | The query exceeded the configured execution deadline |
https://problems.tourfold.com/graphql/filter-too-deep | Filter too deep | The where argument nests more levels than the configured maximum filter depth |
https://problems.tourfold.com/graphql/invalid-cursor | Invalid cursor | The supplied pagination cursor was not produced by this API |
https://problems.tourfold.com/graphql/invalid-pagination | Invalid pagination arguments | The 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 }
}
}
]
}
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/pagination/invalid-page-number | Invalid page number | Page number must be non-negative (0 or greater) | 422 |
https://problems.tourfold.com/pagination/invalid-page-size | Invalid page size | Page size must be between 1 and 1000 | 422 |
Time Range Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/time-range/from-after-to | Invalid time range | The 'from' parameter must be before the 'to' parameter | 422 |
Activity Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/activities/wrong-activity-type | Wrong activity type | Wrong activity type | 422 |
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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/ai-assistant/assistant-disabled | AI assistant is disabled | The 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-progress | AI assistant turn already in progress | Another 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-limited | AI assistant provider is rate limited | The 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/addresses/opening-hours-wrong-format | Opening hours wrong format | Opening hours have a wrong time format | 422 |
Filestore/File Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/filestore/file-not-found | File not found | The referenced file or rendition is not available. | 404 |
https://problems.tourfold.com/filestore/file-deleted | File deleted | The referenced file has been deleted. | 422 |
https://problems.tourfold.com/filestore/storage-object-missing | Storage object missing | The 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-attachable | File is not attachable | Collapsed 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-supported | Rendition source not supported | Renditions can only be generated from image and PDF sources. | 422 |
https://problems.tourfold.com/filestore/rendition-target-format-not-supported | Rendition target format not supported | The requested target format is not supported by the source-specific rendition converter. | 422 |
https://problems.tourfold.com/filestore/rendition-source-decode-failed | Rendition source decode failed | The source file could not be decoded for rendition generation (corrupted or unsupported encoding). | 422 |
https://problems.tourfold.com/filestore/rendition-pdf-empty | Rendition source PDF is empty | The source PDF has no pages. | 422 |
https://problems.tourfold.com/filestore/rendition-alias-reserved | Rendition alias is reserved | The alias original is reserved for the canonical original rendition. | 422 |
https://problems.tourfold.com/filestore/upload-content-empty | Upload content is empty | The upload payload is empty. | 422 |
https://problems.tourfold.com/filestore/upload-mime-type-blank | Upload MIME type is missing | A non-blank MIME type is required for the upload. | 422 |
https://problems.tourfold.com/filestore/upload-original-file-name-blank | Upload original file name is missing | A non-blank original file name is required for the upload. | 422 |
https://problems.tourfold.com/filestore/upload-rejected | Upload rejected | The upload was rejected during completion β size or MIME type does not match the declared values. | 422 |
https://problems.tourfold.com/filestore/storage-purge-incomplete | Storage purge incomplete | A 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/usage/limit-exceeded | Usage limit exceeded | The requested operation would exceed the tenant's configured usage limit | 422 |
Document Management Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/document-management/invalid-name | Invalid name | The 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-taken | Name taken | A live sibling folder or document already uses this name. | 409 |
https://problems.tourfold.com/document-management/parent-not-found | Parent folder not found | The referenced parent folder does not exist. | 404 |
https://problems.tourfold.com/document-management/folder-not-found | Folder not found | The referenced folder does not exist. | 404 |
https://problems.tourfold.com/document-management/move-into-descendant | Move into descendant | A folder cannot be moved into itself or one of its descendants. | 422 |
https://problems.tourfold.com/document-management/move-across-managed-boundary | Move across managed boundary | A 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-target | Invalid move target | The 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-first | Must be soft-deleted first | The 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-folder | Cannot modify managed folder | This 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-document | Cannot modify soft-deleted document | The 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-found | Document not found | The referenced document does not exist or is soft-deleted. | 404 |
https://problems.tourfold.com/document-management/version-not-found | Document version not found | The 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-mismatch | Version MIME mismatch | A 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-rendition | Unsupported download rendition | The 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-failed | Upload initiate failed | The 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-failed | Upload finalize failed | The 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-found | Extraction not found | The referenced extraction does not exist, or it does not belong to a document-management document. | 404 |
https://problems.tourfold.com/document-management/invalid-retention-days | Invalid retention days | The 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/tasks/definition-in-use | Task definition in use | Tasks, 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-use | Required Task relationship in use | A 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-required | Task interaction requires an active human | The 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 |
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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/comments/target-not-found | Target not found | The 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-found | Parent comment not found | The supplied parent_comment_id does not resolve to an existing comment. | 404 |
https://problems.tourfold.com/comments/parent-target-mismatch | Parent comment is on a different target | The supplied parent_comment_id belongs to a different (target_type, target_id) than the new comment. | 422 |
https://problems.tourfold.com/comments/body-too-long | Comment body too long | body_markdown exceeds the configured maximum length. The cap is surfaced in data.max_length. | 422 |
https://problems.tourfold.com/comments/body-invalid-markdown | Comment body contains disallowed markdown | body_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-found | Comment not found | The referenced comment does not exist (or has been hard-deleted). | 404 |
https://problems.tourfold.com/comments/cannot-edit-others | Cannot edit another user's comment | Editing a comment authored by another user requires the comments:update grant. | 403 |
https://problems.tourfold.com/comments/cannot-delete-others | Cannot delete another user's comment | Deleting a comment authored by another user requires the comments:delete grant. | 403 |
https://problems.tourfold.com/comments/moderation-reason-required | Moderation edit requires a reason | Editing another user's comment under the comments:update grant requires a non-blank edit_reason. | 422 |
https://problems.tourfold.com/comments/cannot-restore-not-deleted | Comment is not soft-deleted | Only soft-deleted comments can be restored; the referenced comment is currently live. | 422 |
https://problems.tourfold.com/comments/read-cursor-target-mismatch | Comment does not belong to the supplied target | comment_id in mark-read-until does not belong to the supplied (target_type, target_id). | 422 |
https://problems.tourfold.com/comments/mention-type-unknown | Unknown mention type | A mention token uses a type prefix the server does not understand. | 422 |
https://problems.tourfold.com/comments/mention-target-not-found | Mention target not found | No mention target matches the supplied (type, id) in the current tenant. | 404 |
https://problems.tourfold.com/comments/reaction-on-deleted-comment | Cannot react to a deleted comment | The referenced comment is soft-deleted; reactions can only be added to live comments. | 422 |
https://problems.tourfold.com/comments/reaction-not-found | Reaction not found | DELETE /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-allowed | Attachment MIME type is not allowed | The 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-large | Attachment exceeds per-file size limit | The 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-exceeded | Tenant storage allowance exceeded | The 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-found | Comment attachment not found | The referenced attachment_id does not exist, has been hard-deleted, or has no original rendition. | 404 |
https://problems.tourfold.com/comments/attachment-blob-gone | Attachment blob has been removed | GET /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-comments | Attachment was uploaded for a different feature | The 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-incomplete | Attachment upload not yet completed | The 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-previewable | Attachment cannot be referenced inline | A  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-linked | Inline reference not present in attachment list | The 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-uri | Malformed attachment: reference in body | An image destination uses the attachment: scheme but the suffix is not a valid UUID. | 422 |
https://problems.tourfold.com/comments/too-many-attachments | Comment exceeds attachment count limit | The 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-linked | Attachment is linked to a posted comment | DELETE /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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/notifications/notification-not-found | Notification not found | The 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-url | Notification action URL is not allowed | action_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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/custom-domains/verification-failed | Custom domain verification failed | DNS 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/audit-logs/invalid-time-range | Invalid time range | The 'from' time must be before the 'to' time | 422 |
https://problems.tourfold.com/audit-logs/invalid-sort | Invalid sort parameter | Sorting field or direction is not supported | 422 |
Device Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/devices/registered-to-another-workspace | Device registered to another workspace | This device id is already registered to another workspace | 409 |
https://problems.tourfold.com/devices/device-disabled | Device disabled | This device is disabled and cannot receive telemetry | 403 |
https://problems.tourfold.com/devices/keycloak-enrollment-required | Device enrollment required | This device must enroll into Keycloak before it can authenticate. | 401 |
https://problems.tourfold.com/devices/enrollment-challenge-invalid | Enrollment challenge invalid | The enrollment challenge is invalid, expired, or already used. Request a fresh challenge and retry. | 422 |
https://problems.tourfold.com/devices/setup-link-unsupported-kind | Setup link not supported for this device kind | Setup links are only supported for Tourfold App devices. | 422 |
https://problems.tourfold.com/devices/setup-link-requires-admin-managed-devices | Admin-managed device fleet required | Setup links can only be sent for workspaces whose device fleet is admin-managed. | 422 |
https://problems.tourfold.com/devices/self-enrollment-not-allowed | Self-enrollment not allowed | This workspace provisions devices through admin setup links; a device cannot enroll itself. | 422 |
https://problems.tourfold.com/devices/current-user-association-required | Current human login required | Valid 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-changed | User association changed | The Device has a newer human login. Retain the originally observed episode when retrying logout. | 409 |
https://problems.tourfold.com/devices/vehicle-association-changed | Vehicle association changed | The 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-required | Device token required | Required 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-invalid | Device token invalid | Secondary 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-tour | Device has active tour | Device is associated with a vehicle that currently has an active tour | 422 |
Document Analyzer Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/document-analyzer/schema-invalid | Schema is not valid | The supplied schema could not be parsed as a JSON Schema (Draft 2020-12). | 422 |
https://problems.tourfold.com/document-analyzer/url-not-https | URL must use HTTPS | The document URL must use HTTPS. | 422 |
https://problems.tourfold.com/document-analyzer/url-host-not-allowed | URL host is not allowed | The 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-type | Media type not supported | The declared media type is not supported by the document analyzer. | 422 |
https://problems.tourfold.com/document-analyzer/url-fetch-failed | Could not fetch document URL | The document URL could not be fetched. | 422 |
https://problems.tourfold.com/document-analyzer/document-too-large | Document is too large | The fetched document exceeded the maximum size allowed by the document analyzer. | 422 |
https://problems.tourfold.com/document-analyzer/media-type-mismatch | Document content does not match declared media type | The declared media type does not match the actual document content. | 422 |
https://problems.tourfold.com/document-analyzer/model-output-does-not-match-schema | Model output did not match the schema | The model could not produce a response that conforms to the supplied or inferred JSON Schema. | 422 |
https://problems.tourfold.com/document-analyzer/schema-inference-failed | Could not infer a valid schema from the document | The 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-unavailable | Model provider is unavailable | The upstream model provider is unavailable. Retry the job; if the failure persists, contact support. | 503 |
Geocoding Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/geocoding/no-results | No results | Geocoding returned no results | 404 |
Skill Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/skills/managed | Managed skill | System 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-found | Skill not found | Skill was not found | 404 |
SMS Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/sms/gateway-rejected | SMS gateway rejected the message | The 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-unavailable | SMS gateway unavailable | The 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 Type | Description |
|---|
unresolved-relation | A relation slug in the column's dot-separated field path does not resolve from the root definition |
definition-mismatch | The field path ends in a definition UUID that is not the definition reached at the end of the relation chain |
invalid-filter-operator | The filter operator is not one of the supported GraphQL filter operators |
missing-filter-operator | The filter sets no op and no not filter to negate |
invalid-filter-negation | A filter without op only negates its not filter and must not set value, relative_value, and or or |
missing-filter-value | The filter sets neither value nor relative_value |
ambiguous-filter-value | The filter sets both value and relative_value; they are mutually exclusive |
unsupported-relative-filter-operator | relative_value was used with an operator that cannot compare instants. Supported: _eq, _gt, _lt, _gte, _lte |
invalid-relative-time-expression | relative_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 Type | Description |
|---|
invalid-group-by-attribute | group_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-by | More than one column sets group_by; a view groups by at most one attribute |
missing-group-by | layout 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/tags/not-found | Tag not found | Tag with the given id was not found | 404 |
https://problems.tourfold.com/tags/tag-already-associated | Tag already associated | This tag is already associated with the given resource | 409 |
Template Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/templates/not-found | Template not found | Template was not found | 404 |
https://problems.tourfold.com/templates/rendering-error | Rendering error | Error rendering PDF template | 500 |
https://problems.tourfold.com/templates/todo-not-found | Todo template not found | Todo template was not found | 404 |
Tenant Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/tenants/not-found | Tenant not found | Tenant was not found | 404 |
https://problems.tourfold.com/tenants/template-name-invalid | Invalid template name | Template name must start with 'template_' | 422 |
https://problems.tourfold.com/tenants/source-tenant-is-frozen | Source tenant is frozen | Cannot clone a frozen template tenant as a new template | 422 |
https://problems.tourfold.com/tenants/realm-mode-migration-not-allowed | Realm-mode migration not allowed | Only the SHARED β DEDICATED realm-mode migration is supported. | 422 |
Tenant Reset Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/tenant-reset/reset-not-allowed | Reset not allowed | This workspace cannot be reset. Ask an administrator to enable resets first | 403 |
https://problems.tourfold.com/tenant-reset/active-tours-present | Active tours in progress | This workspace has tours in progress. Finish or cancel them before resetting | 409 |
https://problems.tourfold.com/tenant-reset/no-pending-reset-request | No pending reset request | There is no pending reset to confirm. Request a confirmation code first | 404 |
https://problems.tourfold.com/tenant-reset/invalid-confirmation-code | Invalid confirmation code | The confirmation code provided is not valid | 422 |
https://problems.tourfold.com/tenant-reset/confirmation-code-expired | Confirmation code expired | The confirmation code has expired. Please request a new one | 422 |
https://problems.tourfold.com/tenant-reset/template-not-active | Template not active | The selected template is not available. Choose one of the active templates | 422 |
https://problems.tourfold.com/tenant-reset/confirmation-email-rate-limited | Confirmation email rate limited | Please wait before requesting another confirmation code | 429 |
https://problems.tourfold.com/tenant-reset/owner-email-unavailable | Owner email unavailable | The workspace owner has no email address on file to send the confirmation code to | 422 |
https://problems.tourfold.com/tenant-reset/reset-failed | Reset failed | The workspace could not be reset. Your confirmation code is still valid β please try again | 500 |
Tenant Template Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/tenant-templates/template-not-found | Template not found | The requested tenant template does not exist | 404 |
https://problems.tourfold.com/tenant-templates/tenant-not-frozen | Tenant is not a frozen template | The tenantid_to_clone must reference a frozen tenant (name starts with 'template') | 422 |
Tour Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/tours/tour-ended | Tour ended | The tour has already ended | 422 |
https://problems.tourfold.com/tours/no-user-associated | No user associated | No user is associated with this tour | 422 |
https://problems.tourfold.com/tours/start-time-after-end | Start time after end | Start time must be before scheduled end | 422 |
https://problems.tourfold.com/tours/tour-has-unfinished-activities | Tour has unfinished activities | Cannot finish tour with activities in PENDING or STARTED status | 409 |
https://problems.tourfold.com/tours/tour-template-in-use | Tour template in use | A 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-configuration | Tour template needs configuration | Repair the template before creating a Tour from it; data.tour_template_id identifies the template with unresolved required inputs. | 409 |
Generic Task Toursβ
| Type URI | Title | Recovery | HTTP Status |
|---|
https://problems.tourfold.com/tours/default-template-protected | Default Tour template is protected | Edit 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-conflict | Tour Vehicle use has changed | The 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-active | Device conflicts with active Tour work | A 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-unconfirmed | Device association mode is unconfirmed | An 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-forbidden | Tour execution is not permitted | Join the Tour as an active human participant; data.reason is not_member. | 403 |
https://problems.tourfold.com/tours/human-required | Active human required | Use an active human account; additional grants cannot resolve this restriction. | 403 |
https://problems.tourfold.com/tours/not-published | Tour is not published | Publish before executing. | 409 |
https://problems.tourfold.com/tours/not-started | Tour has not started | Start before finishing. | 409 |
https://problems.tourfold.com/tours/finished | Tour is finished | The Tour and its assigned work are immutable. | 409 |
https://problems.tourfold.com/tours/already-started | Tour has started | Deletion, participant changes and planned-start changes are forbidden. | 409 |
https://problems.tourfold.com/tours/unfinished-work | Tour has unfinished work | Complete or unassign Tasks and standalone Stops before finishing. | 409 |
https://problems.tourfold.com/tours/vehicle-active | Vehicle is in use | Resolve the Vehicleβs active use before starting or changing this Tour. | 409 |
https://problems.tourfold.com/tours/vehicle-required | Vehicle required | First 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-ineligible | Vehicle ineligible | An 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-required | Confirm planned Vehicle assignment | Explicit 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-active | Participant is already active | Finish the blocking Tour identified by data.tour_id or choose another participant. | 409 |
https://problems.tourfold.com/tours/participants-required | Participants required | Select participants before publication. | 409 |
https://problems.tourfold.com/tours/capacity-exceeded | Tour capacity exceeded | At most 500 Stops and 10000 Tasks plus Stops; reduce membership or select another Tour. | 409 |
https://problems.tourfold.com/tours/task-already-assigned | Task already assigned | Move or remove its existing assignment. | 409 |
https://problems.tourfold.com/tours/membership-changed | Membership changed | Reread and submit the complete current order. | 409 |
https://problems.tourfold.com/tours/stop-has-tasks | Stop has assigned Tasks | Unassign its Tasks before deleting the Stop. | 409 |
https://problems.tourfold.com/tours/task-backed-stop | Task completion controls Stop | Complete assigned Tasks rather than directly setting the Stop status. | 409 |
https://problems.tourfold.com/tours/same-stop | Distinct Stops required | Choose different source and destination Stop IDs. | 409 |
Role Errorsβ
| Type URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/roles/system-role-immutable | System role is immutable | System roles cannot be updated or deleted. | 409 |
https://problems.tourfold.com/roles/grant-assignment-denied | Grant assignment denied | Adding 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-denied | Role assignability update denied | Modifying 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/users/already-assigned | User already assigned | User is already assigned | 422 |
https://problems.tourfold.com/users/cannot-delete-self | Cannot delete yourself | Users cannot delete themselves. Carries data.reason: self_target and data.user_id. | 403 |
https://problems.tourfold.com/users/cannot-activate-self | Cannot activate yourself | Users cannot activate themselves. Carries data.reason: self_target and data.user_id. | 403 |
https://problems.tourfold.com/users/cannot-deactivate-self | Cannot deactivate yourself | Users cannot deactivate themselves. Carries data.reason: self_target and data.user_id. | 403 |
https://problems.tourfold.com/users/owner-deletion-conflict | Owner deletion conflict | Transfer 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-owner | Not the workspace owner | Only 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-roles | Cannot change own roles | Changing your own role assignments is forbidden; data.reason is self_target. | 403 |
https://problems.tourfold.com/users/role-assignment-denied | Role assignment denied | The caller cannot assign this role; data.reason is not_member. | 403 |
https://problems.tourfold.com/users/owner-role-change-conflict | Owner role change conflict | Use 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-managed | Profile managed by the user | People 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/vehicles/no-active-device-association | No active device association | No active vehicle device association found | 422 |
https://problems.tourfold.com/vehicles/no-device-association | No device association | No vehicle device association found | 422 |
https://problems.tourfold.com/vehicles/vehicle-already-assigned | Vehicle already assigned | Vehicle is already assigned | 422 |
https://problems.tourfold.com/vehicles/vehicle-has-active-tour | Vehicle has active tour | Vehicle currently has an active tour | 422 |
https://problems.tourfold.com/vehicles/vehicle-not-associated | Vehicle not associated | Vehicle is not associated | 422 |
Vehicle Provider Connection Errorsβ
| Type URI | Title | Recovery | HTTP Status |
|---|
https://problems.tourfold.com/vehicle-provider-connections/account-disabled | Provider account is disabled | Enable the provider account before asking the provider through it. | 409 |
https://problems.tourfold.com/vehicle-provider-connections/authorization-already-requested | Authorization already requested | Consent is already pending or approved; refresh it to learn whether that changed. | 409 |
https://problems.tourfold.com/vehicle-provider-connections/connection-ended | Provider connection has ended | Nothing 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-progress | Provider operation in progress | Wait until the connection's open operation of the same kind settles, then ask again. | 409 |
https://problems.tourfold.com/vehicle-provider-connections/request-id-reused | Request id reused | The 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/not-found | Not found | Object, record, attribute, option, state, or relationship was not found | 404 |
https://problems.tourfold.com/invalid-input | Invalid input | The request body could not be parsed (e.g., malformed or unparseable JSON) | 400 |
https://problems.tourfold.com/validation-failed | Validation failed | Object, attribute, record, query, or permission validation failed | 422 |
https://problems.tourfold.com/resource-conflict | Resource conflict | The supplied lock_version is stale | 409 |
https://problems.tourfold.com/objects/object-definition-in-use | Object definition in use | A 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-use | Object attribute in use | A 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-use | Relationship target in use | The object is targeted by relationship attributes owned by other objects; data.blocking_relationships identifies them | 409 |
https://problems.tourfold.com/objects/count-unit-target-in-use | Count unit target in use | Capacity 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-large | Payload too large | Request payload exceeds the maximum allowed size | 413 |
https://problems.tourfold.com/records/query-timeout | Record query timed out | A structured REST record query exceeded its execution deadline; data.timeout_ms carries the configured limit | 503 |
https://problems.tourfold.com/unknown-error | Unknown error | An 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 Type | Description and pointer |
|---|
field-required | A required input is missing; points to that field, for example #/attributes/0/config/target. |
unknown-field | An unknown config member was sent; points to the exact member. Retired relationship fields such as allowed_objects are rejected this way. |
inapplicable-field | A known config member does not apply to the selected attribute type. |
invalid-enum-value | An enum-like input such as unit_kind has an unsupported value. |
invalid-slug / slug-already-exists / slug-reserved / duplicate-attribute-slug | The object or attribute slug is invalid, duplicated, or reserved. |
attribute-type-required / attribute-type-invalid | Attribute type is missing or unsupported. |
attribute-config-missing | The selected type requires config. |
unique-unsupported-type / unique-immutable | Uniqueness is unsupported for this type or cannot be changed after creation. |
index-unsupported-type | The attribute type cannot carry an index; raw_json documents are never indexed. |
display-template-unknown-attribute | display_template refers to an attribute that does not exist. |
unsupported-display-template-attribute | display_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-items | A 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-link | A 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-deep | A rich_text value or default exceeds the canonical size or nesting limit. |
full-name-component-required | A full_name value carries a title without a first_name or last_name. |
links-unsafe-link | A links URL uses a scheme other than http, https, mailto or tel; the pointer names the link's url. |
links-primary-required | A links value has alternatives but no primary link. |
invalid-icon | icon is not an icon key: use up to 64 lowercase letters, digits and single hyphens. Points to #/icon. |
invalid-pattern / unacceptable-pattern | A text pattern is invalid or uses unsupported non-linear-time features. |
relationship-target-not-found | Singular config.target does not resolve to an object. |
relationship-reverse-slug-conflict | reverse.slug is already used by an owned attribute or relationship on the target object; points to the offending reverse slug. |
relationship-reverse-unsupported | The relationship target does not accept a managed reverse attribute, for example the system user object; points to config.reverse. |
relationship-reverse-managed | A 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-deleted | A 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 Type | Description |
|---|
required-relation | A required relationship value is missing. |
cardinality-violation-source | The source-side cardinality would be exceeded. |
cardinality-violation-target | The target-side cardinality would be exceeded. |
object-not-found | A relationship record id does not exist in its configured target object. |
invalid-reference-value | A 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 URI | Description |
|---|
https://problems.tourfold.com/relation/unknown-field-in-order-by | order_by names a field that is not present on the selected object. |
https://problems.tourfold.com/relation/invalid-sort-direction | The 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 Type | Pointer |
|---|
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 Type | Description |
|---|
type-mismatch | Value does not match the expected type |
required-field | A required field is missing |
invalid-enum-value | Value is not one of the allowed enum values |
invalid-const-value | Value does not match the expected constant |
string-too-short | String length is below the minimum |
string-too-long | String length exceeds the maximum |
pattern-mismatch | String does not match the required pattern |
value-too-small | Numeric value is below the minimum |
value-too-large | Numeric value exceeds the maximum |
not-multiple-of | Numeric value is not a multiple of the required value |
too-few-items | Array has fewer items than allowed |
too-many-items | Array has more items than allowed |
duplicate-items | Array contains duplicate items when uniqueness is required |
invalid-format | Value does not match the required format |
too-few-properties | Object has fewer properties than required |
too-many-properties | Object has more properties than allowed |
additional-properties-not-allowed | Object contains properties not defined in the schema |
oneOf-mismatch | Value does not match exactly one of the oneOf schemas |
anyOf-mismatch | Value does not match any of the anyOf schemas |
allOf-mismatch | Value does not match all of the allOf schemas |
not-mismatch | Value matches a schema it should not |
conditional-mismatch | Value does not satisfy a conditional (if/then/else) schema |
dependent-required | A dependent required property is missing |
dependent-schema-mismatch | Value does not match a dependent schema |
validation-error | Generic validation error (fallback) |
instance-payload-too-large | data 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 pattern | Meaning |
|---|
Validation error (FieldUndefined@...) ... Field ... is undefined | The field is not in your workspace's generated schema. Check the schema endpoint. |
Validation error (WrongType@...) ... not a valid SortDirection | An 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β
| Constraint | Limit | Description |
|---|
| Query length | 10,000 characters | Maximum length of the GraphQL query string |
| Query cost | 100,000 estimated rows | Maximum 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 depth | 12 levels | Maximum 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 time | 10 seconds wall-clock | Maximum time spent executing one operation. Exceeding it returns graphql/query-timeout and interrupts cooperative work. |
Page size (first/last) | 100 | Larger values return graphql/invalid-pagination with the supplied value and maximum. |
| Default page size | 20 (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 depth | 4 | Maximum where recursion depth (_and / _or). Independent of query depth. |
| Relationship order-by nesting | 1 to-one hop | Deeper 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/billing/billing-customer-missing | Billing customer missing | The tenant has no Stripe customer yet, so this billing action is not available | 422 |
https://problems.tourfold.com/billing/plan-change-in-progress | Plan change in progress | A billing plan change is already in progress for this tenant | 409 |
https://problems.tourfold.com/billing/plan-change-not-allowed | Plan change not allowed | The subscription plan cannot be changed in the current billing state | 422 |
https://problems.tourfold.com/billing/seat-cap-exceeded | Seat cap reached | The tenant has reached the maximum number of paid seats allowed by its current plan | 422 |
https://problems.tourfold.com/billing/stripe-billing-unavailable | Stripe billing unavailable | Stripe billing could not be reached or could not process the request | 503 |
https://problems.tourfold.com/billing/plan-configuration-invalid | Plan configuration invalid | The 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/signup/email-not-verified | Email not verified | Verify your email before continuing with the signup flow | 409 |
https://problems.tourfold.com/signup/invalid-verification-code | Invalid verification code | The verification code is not valid, was used up by five wrong attempts, or no signup exists for the email; all answer alike | 422 |
https://problems.tourfold.com/signup/verification-code-expired | Verification code expired | The verification code has expired; request a new one | 422 |
https://problems.tourfold.com/signup/subdomain-not-available | Subdomain not available | The requested subdomain is already taken | 409 |
https://problems.tourfold.com/signup/subdomain-reserved | Subdomain reserved | The requested subdomain is reserved and cannot be used | 409 |
https://problems.tourfold.com/signup/subdomain-invalid-format | Invalid subdomain format | Subdomain must use 3-16 lowercase alphanumeric characters | 422 |
https://problems.tourfold.com/signup/session-not-found | Session not found | The signup session does not exist | 404 |
https://problems.tourfold.com/signup/session-already-completed | Session already completed | The signup session has already been completed | 409 |
https://problems.tourfold.com/signup/session-not-ready | Session not ready | Complete all required steps before finishing the signup | 422 |
https://problems.tourfold.com/signup/payment-pending | Payment pending | The payment is still processing. Please wait and try again | 409 |
https://problems.tourfold.com/signup/completion-in-progress | Signup completion in progress | The signup is already being completed. Please wait and try again | 409 |
https://problems.tourfold.com/signup/payment-not-completed | Payment not completed | The payment has not completed | 409 |
https://problems.tourfold.com/signup/payment-failed | Payment failed | The payment failed. Please choose a plan and try again | 409 |
https://problems.tourfold.com/signup/email-rate-limited | Email rate limited | Too many verification requests in a short period | 429 |
https://problems.tourfold.com/signup/invalid-invite-code | Invalid invite code | The invite code provided is not valid | 422 |
https://problems.tourfold.com/signup/email-sending-failed | Email sending failed | The verification email could not be sent | 503 |
https://problems.tourfold.com/signup/tenant-creation-failed | Tenant creation failed | The platform could not create a tenant for this signup | 500 |
https://problems.tourfold.com/signup/account-link-required | Account link required | The 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-rejected | Account link rejected | The 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-incomplete | Account profile incomplete | The 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 URI | Title | Description | HTTP Status |
|---|
https://problems.tourfold.com/capacity/not-found | Measure unit not found | Measure unit was not found | 404 |
https://problems.tourfold.com/capacity/measure-unit-in-use | Measure unit in use | Object, 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.