{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors","projectTitle":"Frontline Documentation"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors","__idx":0},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Frontline Public API returns errors as JSON with a consistent envelope, an HTTP status code, and a machine-readable error code."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-envelope","__idx":1},"children":["Error envelope"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"ok\": false,\n    \"error\": {\n        \"code\": \"bad_request\",\n        \"message\": \"Human-readable description of what went wrong.\",\n        \"details\": {\n            /* optional, present on validation errors */\n        }\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ok"]}," is always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," on error responses."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]}," is a stable, machine-readable string. Branch on this instead of parsing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," is meant for humans and may change without notice."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," and appears mainly on validation failures (e.g. zod issues from the request body or query)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"status-codes-and-error-codes","__idx":2},"children":["Status codes and error codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP"},"children":["HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"error.code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it happens"},"children":["When it happens"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bad_request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validation failed (body, params, query). Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}," for the offending fields."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cli_outdated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@getfrontline/cli"]}," below the minimum supported version. See \"CLI outdated\" below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unauthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing, malformed, revoked, or wrong-scope API key. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/authentication"},"children":["Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["402"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subscription/billing gate (e.g. plan does not allow the operation)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["forbidden"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key is valid but does not have access to the target resource."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The resource does not exist or has been soft-deleted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conflict"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uniqueness or relational constraint violated (e.g. duplicate name, foreign key)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/rate-limits"},"children":["Rate limits"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unexpected server error. Safe to retry once; if it persists, report it."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validation-errors--400-bad_request-","__idx":3},"children":["Validation errors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 bad_request"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When zod rejects the request body or query string, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}," carries the structured issues:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"ok\": false,\n    \"error\": {\n        \"code\": \"bad_request\",\n        \"message\": \"Invalid request\",\n        \"details\": {\n            \"issues\": [\n                {\n                    \"path\": [\"name\"],\n                    \"message\": \"String must contain at least 1 character(s)\",\n                    \"code\": \"too_small\"\n                }\n            ]\n        }\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.issues[].path"]}," to highlight the bad field in your UI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," on each issue is one of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A standard zod code (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["too_small"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["too_big"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_enum_value"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_string"]},", …) for shape errors caught by request validation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One of the Public-API codes below for cross-resource validation:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it appears"},"children":["When it appears"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A referenced id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aiModelId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customToolIds[]"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentIds[]"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assistantId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tableId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["triggeredByAgentIds[]"]},", etc.) does not exist or is not accessible from the caller's account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wrong_kind"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The reference exists but does not match the surrounding constraint (e.g. a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recordTypeId"]}," that does not belong to the given ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tableId"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wrong_owner"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The reference exists in the platform but belongs to a different account."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-node-references","__idx":4},"children":["Example: node references"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a flow or workflow node with references to resources that don't exist, the API rejects the request ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," persisting anything and returns every offending reference in a single response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"ok\": false,\n    \"error\": {\n        \"code\": \"bad_request\",\n        \"message\": \"One or more node references are invalid\",\n        \"details\": {\n            \"issues\": [\n                {\n                    \"path\": [\"data\", \"aiModelId\"],\n                    \"code\": \"not_found\",\n                    \"value\": 99999999,\n                    \"message\": \"AI model 99999999 does not exist.\"\n                },\n                {\n                    \"path\": [\"data\", \"customToolIds\", 0],\n                    \"code\": \"not_found\",\n                    \"value\": 42,\n                    \"message\": \"Tool 42 does not exist or is not accessible from this account.\"\n                }\n            ]\n        }\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issue.code === \"not_found\""]}," to highlight the broken reference; the human-readable message tells the end user which id was rejected."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cli-outdated--400-cli_outdated-","__idx":5},"children":["CLI outdated (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 cli_outdated"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returned exclusively to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@getfrontline/cli"]}," binaries when the client version is older than the minimum the server supports. The payload includes extra context:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"ok\": false,\n    \"error\": {\n        \"code\": \"cli_outdated\",\n        \"message\": \"CLI version is too old. Please update @getfrontline/cli.\",\n        \"details\": { \"minSupportedVersion\": \"1.0.9\" },\n        \"suggestion\": \"Update with: npm i -g @getfrontline/cli (or your package manager equivalent).\"\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The CLI handles this automatically and prints ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["suggestion"]}," to the user."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-client-handling","__idx":6},"children":["Recommended client handling"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"async function callApi(path, init) {\n    const res = await fetch(`https://prod-api.getfrontline.ai/public/v1${path}`, init);\n    const body = await res.json().catch(() => ({}));\n\n    if (!res.ok) {\n        const code = body?.error?.code ?? \"unknown\";\n        const message = body?.error?.message ?? res.statusText;\n        throw Object.assign(new Error(message), {\n            code,\n            status: res.status,\n            details: body?.error?.details,\n        });\n    }\n\n    return body;\n}\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["err.code"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unauthorized"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conflict"]},", …) in your business logic; only show ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["err.message"]}," to end users."]}]},"headings":[{"value":"Errors","id":"errors","depth":1},{"value":"Error envelope","id":"error-envelope","depth":2},{"value":"Status codes and error codes","id":"status-codes-and-error-codes","depth":2},{"value":"Validation errors ( 400 bad_request )","id":"validation-errors--400-bad_request-","depth":2},{"value":"Example: node references","id":"example-node-references","depth":3},{"value":"CLI outdated ( 400 cli_outdated )","id":"cli-outdated--400-cli_outdated-","depth":2},{"value":"Recommended client handling","id":"recommended-client-handling","depth":2}],"frontmatter":{"seo":{"title":"Errors"}},"lastModified":"2026-05-28T14:34:48.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}