[{"data":1,"prerenderedAt":3122},["ShallowReactive",2],{"navigation_docs_en":3,"-en-reference-extensions-data-connectors-errors":445,"-en-reference-extensions-data-connectors-errors-surround":3117},[4,30,72,132,260,436],{"title":5,"icon":6,"path":7,"stem":8,"children":9,"page":6},"Getting Started",false,"\u002Fen\u002Fgetting-started","en\u002F1.getting-started",[10,15,20,25],{"title":11,"path":12,"stem":13,"icon":14},"Introduction","\u002Fen\u002Fgetting-started\u002Fintroduction","en\u002F1.getting-started\u002F2.introduction","i-lucide-house",{"title":16,"path":17,"stem":18,"icon":19},"Quickstart","\u002Fen\u002Fgetting-started\u002Finstallation","en\u002F1.getting-started\u002F3.installation","i-lucide-download",{"title":21,"path":22,"stem":23,"icon":24},"Use Cases","\u002Fen\u002Fgetting-started\u002Fuse-cases","en\u002F1.getting-started\u002F4.use-cases","i-lucide-layers",{"title":26,"path":27,"stem":28,"icon":29},"Concepts","\u002Fen\u002Fgetting-started\u002Fconcepts","en\u002F1.getting-started\u002F5.concepts","i-lucide-book",{"title":26,"path":31,"stem":32,"children":33,"page":6},"\u002Fen\u002Fconcepts","en\u002F2.concepts",[34,38,43,48,53,58,63,68],{"title":35,"path":36,"stem":37,"icon":14},"Organization","\u002Fen\u002Fconcepts\u002Forganization","en\u002F2.concepts\u002F1.organization",{"title":39,"path":40,"stem":41,"icon":42},"Data Model","\u002Fen\u002Fconcepts\u002Fdata-model","en\u002F2.concepts\u002F2.data-model","i-lucide-database",{"title":44,"path":45,"stem":46,"icon":47},"Access Control","\u002Fen\u002Fconcepts\u002Faccess-permissions","en\u002F2.concepts\u002F3.access-permissions","i-lucide-user-key",{"title":49,"path":50,"stem":51,"icon":52},"Audit Logs","\u002Fen\u002Fconcepts\u002Faudit-logs","en\u002F2.concepts\u002F4.audit-logs","i-lucide-scroll-text",{"title":54,"path":55,"stem":56,"icon":57},"Introspection","\u002Fen\u002Fconcepts\u002Fintrospection","en\u002F2.concepts\u002F6.introspection","i-lucide-database-search",{"title":59,"path":60,"stem":61,"icon":62},"Query Engine","\u002Fen\u002Fconcepts\u002Fquery-engine","en\u002F2.concepts\u002F7.query-engine","i-lucide-workflow",{"title":64,"path":65,"stem":66,"icon":67},"AI","\u002Fen\u002Fconcepts\u002Fai","en\u002F2.concepts\u002F8.ai","i-lucide-sparkles",{"title":69,"path":70,"stem":71,"icon":42},"Caching","\u002Fen\u002Fconcepts\u002Fcaching","en\u002F2.concepts\u002F9.caching",{"title":73,"path":74,"stem":75,"children":76,"page":6},"Guides","\u002Fen\u002Fguides","en\u002F4.guides",[77,82,87,92,97,102,107,112],{"title":78,"path":79,"stem":80,"icon":81},"REST API Quickstart","\u002Fen\u002Fguides\u002Frest-api","en\u002F4.guides\u002F1.rest-api","i-lucide-plug",{"title":83,"path":84,"stem":85,"icon":86},"SDK Quickstart","\u002Fen\u002Fguides\u002Fsdk","en\u002F4.guides\u002F2.sdk","i-lucide-terminal",{"title":88,"path":89,"stem":90,"icon":91},"Configure SSO","\u002Fen\u002Fguides\u002Fconfigure-sso","en\u002F4.guides\u002F3.configure-sso","i-lucide-key-round",{"title":93,"path":94,"stem":95,"icon":96},"Configure MCP","\u002Fen\u002Fguides\u002Fmcp","en\u002F4.guides\u002F4.mcp","i-lucide-brain-cog",{"title":98,"path":99,"stem":100,"icon":101},"Customize Content Space","\u002Fen\u002Fguides\u002Fcustomize-content-space","en\u002F4.guides\u002F5.customize-content-space","i-lucide-columns-3-cog",{"title":103,"path":104,"stem":105,"icon":106},"Build an Application with AI Assistance","\u002Fen\u002Fguides\u002Fbuild-an-application","en\u002F4.guides\u002F6.build-an-application","i-lucide-route",{"title":108,"path":109,"stem":110,"icon":111},"Horizontal Scaling","\u002Fen\u002Fguides\u002Fhorizontal-scaling","en\u002F4.guides\u002F7.horizontal-scaling","i-lucide-network",{"title":113,"icon":114,"path":115,"stem":116,"children":117,"page":6},"Data Connectors","i-lucide-cable","\u002Fen\u002Fguides\u002Fdata-connectors","en\u002F4.guides\u002F8.data-connectors",[118,122,127],{"title":16,"path":119,"stem":120,"icon":121},"\u002Fen\u002Fguides\u002Fdata-connectors\u002Fquickstart","en\u002F4.guides\u002F8.data-connectors\u002F1.quickstart","i-lucide-rocket",{"title":123,"path":124,"stem":125,"icon":126},"Build a Stripe Connector","\u002Fen\u002Fguides\u002Fdata-connectors\u002Fstripe","en\u002F4.guides\u002F8.data-connectors\u002F2.stripe","i-lucide-hammer",{"title":128,"path":129,"stem":130,"icon":131},"Build with AI Agents","\u002Fen\u002Fguides\u002Fdata-connectors\u002Fai-agents","en\u002F4.guides\u002F8.data-connectors\u002F3.ai-agents","i-lucide-bot",{"title":133,"path":134,"stem":135,"children":136,"page":6},"Developer","\u002Fen\u002Fdeveloper","en\u002F5.developer",[137,191,215,220],{"title":138,"path":139,"stem":140,"children":141,"page":6},"Data Access","\u002Fen\u002Fdeveloper\u002Fapi","en\u002F5.developer\u002F1.api",[142,147,152,157,162,167,172,177,182,186],{"title":143,"path":144,"stem":145,"icon":146},"Overview","\u002Fen\u002Fdeveloper\u002Fapi\u002Foverview","en\u002F5.developer\u002F1.api\u002F1.overview","i-lucide-globe",{"title":148,"path":149,"stem":150,"icon":151},"Errors","\u002Fen\u002Fdeveloper\u002Fapi\u002Ferrors","en\u002F5.developer\u002F1.api\u002F10.errors","i-lucide-alert-triangle",{"title":153,"path":154,"stem":155,"icon":156},"Authentication","\u002Fen\u002Fdeveloper\u002Fapi\u002Fauthentication","en\u002F5.developer\u002F1.api\u002F2.authentication","i-lucide-lock",{"title":158,"path":159,"stem":160,"icon":161},"Reading Data","\u002Fen\u002Fdeveloper\u002Fapi\u002Freading-data","en\u002F5.developer\u002F1.api\u002F3.reading-data","i-lucide-book-open",{"title":163,"path":164,"stem":165,"icon":166},"Writing Data","\u002Fen\u002Fdeveloper\u002Fapi\u002Fwriting-data","en\u002F5.developer\u002F1.api\u002F4.writing-data","i-lucide-pencil",{"title":168,"path":169,"stem":170,"icon":171},"Filtering","\u002Fen\u002Fdeveloper\u002Fapi\u002Ffiltering","en\u002F5.developer\u002F1.api\u002F5.filtering","i-lucide-filter",{"title":173,"path":174,"stem":175,"icon":176},"Field Selection","\u002Fen\u002Fdeveloper\u002Fapi\u002Ffield-selection","en\u002F5.developer\u002F1.api\u002F6.field-selection","i-lucide-list-checks",{"title":178,"path":179,"stem":180,"icon":181},"Sorting & Pagination","\u002Fen\u002Fdeveloper\u002Fapi\u002Fsorting-pagination","en\u002F5.developer\u002F1.api\u002F7.sorting-pagination","i-lucide-arrow-up-down",{"title":183,"path":184,"stem":185,"icon":111},"Relational Data","\u002Fen\u002Fdeveloper\u002Fapi\u002Frelational-data","en\u002F5.developer\u002F1.api\u002F8.relational-data",{"title":187,"path":188,"stem":189,"icon":190},"Files & Assets","\u002Fen\u002Fdeveloper\u002Fapi\u002Ffiles","en\u002F5.developer\u002F1.api\u002F9.files","i-lucide-file-up",{"title":192,"path":193,"stem":194,"children":195,"page":6},"Client SDK","\u002Fen\u002Fdeveloper\u002Fsdk","en\u002F5.developer\u002F2.sdk",[196,200,205,210],{"title":197,"path":198,"stem":199,"icon":19},"Installation","\u002Fen\u002Fdeveloper\u002Fsdk\u002Finstallation","en\u002F5.developer\u002F2.sdk\u002F1.installation",{"title":201,"path":202,"stem":203,"icon":204},"Client Setup","\u002Fen\u002Fdeveloper\u002Fsdk\u002Fclient-setup","en\u002F5.developer\u002F2.sdk\u002F2.client-setup","i-lucide-settings",{"title":206,"path":207,"stem":208,"icon":209},"Type System","\u002Fen\u002Fdeveloper\u002Fsdk\u002Ftype-system","en\u002F5.developer\u002F2.sdk\u002F3.type-system","i-lucide-braces",{"title":211,"path":212,"stem":213,"icon":214},"Advanced","\u002Fen\u002Fdeveloper\u002Fsdk\u002Fadvanced","en\u002F5.developer\u002F2.sdk\u002F5.advanced","i-lucide-puzzle",{"title":216,"path":217,"stem":218,"icon":219},"Application Users","\u002Fen\u002Fdeveloper\u002Fapplication-users","en\u002F5.developer\u002F3.application-users","i-lucide-users",{"title":221,"path":222,"stem":223,"children":224,"icon":214},"Extensions","\u002Fen\u002Fdeveloper\u002Fextensions","en\u002F5.developer\u002F3.extensions\u002Findex",[225,226,231],{"title":143,"path":222,"stem":223,"icon":214},{"title":227,"path":228,"stem":229,"icon":230},"Install and Manage Extensions","\u002Fen\u002Fdeveloper\u002Fextensions\u002Finstall","en\u002F5.developer\u002F3.extensions\u002F1.install","i-lucide-package-plus",{"title":113,"path":232,"stem":233,"children":234,"icon":114},"\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002Findex",[235,236,241,245,250,255],{"title":143,"path":232,"stem":233,"icon":114},{"title":237,"path":238,"stem":239,"icon":240},"How Data Connectors Run","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fruntime","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F2.runtime","i-lucide-cpu",{"title":242,"path":243,"stem":244,"icon":42},"Data Sources","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-sources","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F3.data-sources",{"title":246,"path":247,"stem":248,"icon":249},"Map an External Data Source","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-source-mapping","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F4.data-source-mapping","i-lucide-map",{"title":251,"path":252,"stem":253,"icon":254},"Handle Errors","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Ferrors","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F5.errors","i-lucide-shield-alert",{"title":256,"path":257,"stem":258,"icon":259},"Test a Data Connector","\u002Fen\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Ftesting","en\u002F5.developer\u002F3.extensions\u002F2.data-connectors\u002F6.testing","i-lucide-flask-conical",{"title":261,"path":262,"stem":263,"children":264,"page":6},"Reference","\u002Fen\u002Freference","en\u002F6.reference",[265,269,274,279,295,299,304,340,369,374],{"title":266,"path":267,"stem":268,"icon":204},"Configuration","\u002Fen\u002Freference\u002Fenvironment-variables","en\u002F6.reference\u002F1.environment-variables",{"title":270,"path":271,"stem":272,"icon":273},"System Requirements","\u002Fen\u002Freference\u002Fsystem-requirements","en\u002F6.reference\u002F2.system-requirements","i-lucide-server",{"title":275,"path":276,"stem":277,"icon":278},"Licensing","\u002Fen\u002Freference\u002Flicensing","en\u002F6.reference\u002F3.licensing","i-lucide-gem",{"title":280,"path":281,"stem":282,"children":283,"icon":81},"Connectors","\u002Fen\u002Freference\u002Fconnectors","en\u002F6.reference\u002F4.connectors\u002Findex",[284,285,290],{"title":280,"path":281,"stem":282,"icon":81},{"title":286,"path":287,"stem":288,"icon":289},"PostgreSQL and Supabase","\u002Fen\u002Freference\u002Fconnectors\u002Fpostgresql-supabase","en\u002F6.reference\u002F4.connectors\u002F1.postgresql-supabase","i-simple-icons-postgresql",{"title":291,"path":292,"stem":293,"icon":294},"MySQL and MariaDB","\u002Fen\u002Freference\u002Fconnectors\u002Fmysql-mariadb","en\u002F6.reference\u002F4.connectors\u002F2.mysql-mariadb","i-simple-icons-mysql",{"title":296,"path":297,"stem":298,"icon":209},"Data Types Representation","\u002Fen\u002Freference\u002Fdata-types","en\u002F6.reference\u002F5.data-types",{"title":300,"path":301,"stem":302,"icon":303},"Permissions Reference","\u002Fen\u002Freference\u002Fpermissions","en\u002F6.reference\u002F6.permissions","i-lucide-shield",{"title":305,"path":306,"stem":307,"children":308,"page":6},"API Reference","\u002Fen\u002Freference\u002Fapi-reference","en\u002F6.reference\u002F7.api-reference",[309,313,318],{"title":310,"path":311,"stem":312,"icon":273},"System Endpoints","\u002Fen\u002Freference\u002Fapi-reference\u002Fsystem-endpoints","en\u002F6.reference\u002F7.api-reference\u002F1.system-endpoints",{"title":314,"path":315,"stem":316,"icon":317},"OpenAPI Spec","\u002Fen\u002Freference\u002Fapi-reference\u002Fopenapi-spec","en\u002F6.reference\u002F7.api-reference\u002F2.openapi-spec","i-lucide-file-code",{"title":319,"path":320,"stem":321,"children":322,"icon":324},"Schema Migration","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002Findex",[323,325,330,335],{"title":319,"path":320,"stem":321,"icon":324},"i-lucide-database-zap",{"title":326,"path":327,"stem":328,"icon":329},"Apply Migrations","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Fapply-migrations","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002F1.apply-migrations","i-lucide-upload",{"title":331,"path":332,"stem":333,"icon":334},"Import Changes","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Fimport-changes","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002F2.import-changes","i-lucide-refresh-cw",{"title":336,"path":337,"stem":338,"icon":339},"Operation Reference","\u002Fen\u002Freference\u002Fapi-reference\u002Fschema-migration\u002Foperation-reference","en\u002F6.reference\u002F7.api-reference\u002F3.schema-migration\u002F3.operation-reference","i-lucide-list-tree",{"title":341,"path":342,"stem":343,"children":344,"page":6},"Design Considerations","\u002Fen\u002Freference\u002Fdesign-considerations","en\u002F6.reference\u002F8.design-considerations",[345,349,354,359,364],{"title":143,"path":346,"stem":347,"icon":348},"\u002Fen\u002Freference\u002Fdesign-considerations\u002Foverview","en\u002F6.reference\u002F8.design-considerations\u002F1.overview","i-lucide-compass",{"title":350,"path":351,"stem":352,"icon":353},"Instance Configuration","\u002Fen\u002Freference\u002Fdesign-considerations\u002Finstance-configuration-related-problems","en\u002F6.reference\u002F8.design-considerations\u002F3.instance-configuration-related-problems","i-lucide-wrench",{"title":355,"path":356,"stem":357,"icon":358},"Overly Permissive Public Access","\u002Fen\u002Freference\u002Fdesign-considerations\u002Foverly-permissive","en\u002F6.reference\u002F8.design-considerations\u002F4.overly-permissive","i-lucide-shield-off",{"title":360,"path":361,"stem":362,"icon":363},"No Aggregates","\u002Fen\u002Freference\u002Fdesign-considerations\u002Fno-aggregates","en\u002F6.reference\u002F8.design-considerations\u002F5.no-aggregates","i-lucide-sigma",{"title":365,"path":366,"stem":367,"icon":368},"Cross-Data-Source Referential Integrity","\u002Fen\u002Freference\u002Fdesign-considerations\u002Fcross-data-source-referential-integrity","en\u002F6.reference\u002F8.design-considerations\u002F6.cross-data-source-referential-integrity","i-lucide-unlink",{"title":370,"path":371,"stem":372,"icon":373},"CLI","\u002Fen\u002Freference\u002Fcli","en\u002F6.reference\u002F9.cli","i-lucide-square-terminal",{"title":221,"path":375,"stem":376,"children":377,"page":6},"\u002Fen\u002Freference\u002Fextensions","en\u002F6.reference\u002F9.extensions",[378,383,386,405],{"title":379,"path":380,"stem":381,"icon":382},"Extension Config and Manifest","\u002Fen\u002Freference\u002Fextensions\u002Fmanifest","en\u002F6.reference\u002F9.extensions\u002F1.manifest","i-lucide-file-json",{"title":370,"path":384,"stem":385,"icon":86},"\u002Fen\u002Freference\u002Fextensions\u002Fcli","en\u002F6.reference\u002F9.extensions\u002F2.cli",{"title":387,"path":388,"stem":389,"children":390,"page":6},"Extension Kit","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit",[391,395,400],{"title":392,"path":393,"stem":394,"icon":81},"Data Connector","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit\u002Fdata-connector","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit\u002F1.data-connector",{"title":396,"path":397,"stem":398,"icon":399},"Protocol","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit\u002Fprotocol","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit\u002F2.protocol","i-lucide-arrow-left-right",{"title":401,"path":402,"stem":403,"icon":404},"Schema Helpers","\u002Fen\u002Freference\u002Fextensions\u002Fextension-kit\u002Fexperimental","en\u002F6.reference\u002F9.extensions\u002F3.extension-kit\u002F3.experimental","i-lucide-blocks",{"title":113,"path":406,"stem":407,"children":408,"page":6},"\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors",[409,413,417,421,426,431],{"title":410,"path":411,"stem":412,"icon":81},"Data Connector API","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F1.api",{"title":414,"path":415,"stem":416,"icon":176},"Operations and Operators","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F2.operations",{"title":148,"path":418,"stem":419,"icon":420},"\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Ferrors","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F3.errors","i-lucide-triangle-alert",{"title":422,"path":423,"stem":424,"icon":425},"Runtime Limits","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Flimits","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F4.limits","i-lucide-gauge",{"title":427,"path":428,"stem":429,"icon":430},"Limitations","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Flimitations","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F5.limitations","i-lucide-ban",{"title":432,"path":433,"stem":434,"icon":435},"Network Permissions","\u002Fen\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fpermissions","en\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F6.permissions","i-lucide-shield-check",{"title":437,"icon":121,"path":438,"stem":439,"children":440,"page":6},"Release Notes","\u002Fen\u002Frelease-notes","en\u002F7.release-notes",[441],{"title":442,"path":443,"stem":444,"icon":121},"Changelog","\u002Fen\u002Frelease-notes\u002Fchangelog","en\u002F7.release-notes\u002F1.changelog",{"id":446,"title":447,"body":448,"description":3110,"extension":3111,"links":3112,"meta":3113,"navigation":3114,"path":418,"seo":3115,"stem":419,"__hash__":3116},"docs_en\u002Fen\u002F6.reference\u002F9.extensions\u002F4.data-connectors\u002F3.errors.md","Data Connector Errors",{"type":449,"value":450,"toc":3096},"minimark",[451,454,459,472,500,1410,1480,1487,1502,1517,1521,1680,1705,1734,1765,1775,1780,1789,1923,1944,1947,1950,1988,1996,2001,2005,2008,2054,2066,2070,2078,2147,2157,2247,2251,2257,2331,2350,2353,2357,2363,2396,2403,2406,2416,2599,2602,2677,2683,2696,2699,2806,2810,2820,2907,2912,3061,3064,3068,3092],[452,453],"preview",{},[455,456,458],"h2",{"id":457},"throw-a-connector-error","Throw a Connector Error",[460,461,462,463,467,468,471],"p",{},"A data connector extension reports a failure by throwing one of the kit's error classes from ",[464,465,466],"code",{},"setup"," or a handler. Import them from ",[464,469,470],{},"@monospace\u002Fextension-kit\u002Fdata-connector",".",[460,473,474,475,479,480,483,484,487,488,491,492,495,496,499],{},"The connector exposes an external data source as ",[476,477,478],"strong",{},"collections",", which are containers for ",[476,481,482],{},"items"," of the same type. An item is a single data object, and its named values are ",[476,485,486],{},"fields",". This excerpt from the Stripe example's client throws a kit class when the Stripe API can't be reached or doesn't answer in time. It reads the body inside the same ",[464,489,490],{},"try",", and keeps the rejection as ",[464,493,494],{},"cause","; ",[464,497,498],{},"\u002F\u002F …"," marks the lines it leaves out:",[501,502,503],"accordion",{},[504,505,507],"accordion-item",{"label":506},"src\u002Fdata-connectors\u002Fstripe\u002Fclient.ts",[508,509,514],"pre",{"className":510,"code":511,"filename":506,"language":512,"meta":513,"style":513},"language-ts shiki shiki-themes monospace-light monospace-light monospace-dark","import {\n    AccessDenied,\n    ConnectionFailed,\n    ForeignKeyConstraintViolation,\n    NullConstraintViolation,\n    QueryRejected,\n    RateLimited,\n    UniqueConstraintViolation,\n} from '@monospace\u002Fextension-kit\u002Fdata-connector';\n\u002F\u002F Pinned next to the field paths it governs; see collections.ts.\nimport { STRIPE_API_VERSION } from '.\u002Fcollections';\n\nconst BASE_URL = 'https:\u002F\u002Fapi.stripe.com\u002Fv1\u002F';\n\u002F** Engine sets no deadline on `query` or `testConnection`, so every request carries its own. *\u002F\nconst TIMEOUT_MS = 10_000;\n\u002F** The most objects Stripe returns per list request. *\u002F\nconst PAGE_SIZE = 100;\n\u002F** Stripe ids are letters, digits, `_` and `-`. Anything else can't name an object. *\u002F\nconst STRIPE_ID = \u002F^[\\w-]+$\u002Fu;\n    \u002F\u002F …\n    \u002F** Sends one request and reads the whole body within the deadline. Throws only when no answer arrives. *\u002F\n    async #send(method: Method, path: string, form?: URLSearchParams): Promise\u003CStripeResponse> {\n        const headers: Record\u003Cstring, string> = { 'Authorization': `Bearer ${this.#apiKey}`, 'Stripe-Version': STRIPE_API_VERSION };\n        const init: RequestInit = { method, headers, signal: AbortSignal.timeout(TIMEOUT_MS) };\n\n        if (form !== undefined) {\n            headers['Content-Type'] = 'application\u002Fx-www-form-urlencoded';\n            init.body = form.toString();\n        }\n\n        let response: Response;\n        let text: string;\n\n        try {\n            response = await fetch(new URL(path, BASE_URL), init);\n            text = await response.text();\n        }\n        catch (error) {\n            const isTimeout = error instanceof Error && error.name === 'TimeoutError';\n            const reason = isTimeout ? `did not answer within ${TIMEOUT_MS \u002F 1000} seconds` : 'could not be reached';\n            \u002F\u002F Keep the rejection as the `cause`: when the data source's permissions refused the request,\n            \u002F\u002F Engine finds that there and reports a permission error instead of a failed connection.\n            throw new ConnectionFailed(`The Stripe API ${reason}.`, { cause: error });\n        }\n\n        return { status: response.status, ok: response.ok, body: parseJson(text), headers: response.headers };\n    }\n}\n\n\u002F** The body of a successful response; any other response becomes an error. *\u002F\nfunction checked(response: StripeResponse, method: Method, path: string): unknown {\n    if (!response.ok) throw toConnectorError(response, method, path);\n    \u002F\u002F A changed API, not something the caller can fix: a plain error, which Engine reports as a failed query.\n    if (response.body === undefined) throw new Error('Stripe returned a response that is not JSON.');\n    return response.body;\n}\n","ts","",[464,515,516,529,539,547,555,563,571,579,587,603,610,631,638,656,662,677,683,698,704,734,740,746,810,857,896,901,921,933,939,945,950,961,976,981,989,1029,1050,1055,1068,1106,1143,1149,1155,1186,1191,1196,1244,1250,1256,1261,1267,1311,1351,1357,1391,1405],{"__ignoreMap":513},[517,518,521,525],"span",{"class":519,"line":520},"line",1,[517,522,524],{"class":523},"sLVBU","import",[517,526,528],{"class":527},"sTMul"," {\n",[517,530,532,536],{"class":519,"line":531},2,[517,533,535],{"class":534},"sNJ9c","    AccessDenied",[517,537,538],{"class":527},",\n",[517,540,542,545],{"class":519,"line":541},3,[517,543,544],{"class":534},"    ConnectionFailed",[517,546,538],{"class":527},[517,548,550,553],{"class":519,"line":549},4,[517,551,552],{"class":534},"    ForeignKeyConstraintViolation",[517,554,538],{"class":527},[517,556,558,561],{"class":519,"line":557},5,[517,559,560],{"class":534},"    NullConstraintViolation",[517,562,538],{"class":527},[517,564,566,569],{"class":519,"line":565},6,[517,567,568],{"class":534},"    QueryRejected",[517,570,538],{"class":527},[517,572,574,577],{"class":519,"line":573},7,[517,575,576],{"class":534},"    RateLimited",[517,578,538],{"class":527},[517,580,582,585],{"class":519,"line":581},8,[517,583,584],{"class":534},"    UniqueConstraintViolation",[517,586,538],{"class":527},[517,588,590,593,596,600],{"class":519,"line":589},9,[517,591,592],{"class":527},"} ",[517,594,595],{"class":523},"from",[517,597,599],{"class":598},"suKVh"," '@monospace\u002Fextension-kit\u002Fdata-connector'",[517,601,602],{"class":527},";\n",[517,604,606],{"class":519,"line":605},10,[517,607,609],{"class":608},"seNfP","\u002F\u002F Pinned next to the field paths it governs; see collections.ts.\n",[517,611,613,615,618,621,624,626,629],{"class":519,"line":612},11,[517,614,524],{"class":523},[517,616,617],{"class":527}," { ",[517,619,620],{"class":534},"STRIPE_API_VERSION",[517,622,623],{"class":527}," } ",[517,625,595],{"class":523},[517,627,628],{"class":598}," '.\u002Fcollections'",[517,630,602],{"class":527},[517,632,634],{"class":519,"line":633},12,[517,635,637],{"emptyLinePlaceholder":636},true,"\n",[517,639,641,644,648,651,654],{"class":519,"line":640},13,[517,642,643],{"class":523},"const",[517,645,647],{"class":646},"ssBNi"," BASE_URL",[517,649,650],{"class":523}," =",[517,652,653],{"class":598}," 'https:\u002F\u002Fapi.stripe.com\u002Fv1\u002F'",[517,655,602],{"class":527},[517,657,659],{"class":519,"line":658},14,[517,660,661],{"class":608},"\u002F** Engine sets no deadline on `query` or `testConnection`, so every request carries its own. *\u002F\n",[517,663,665,667,670,672,675],{"class":519,"line":664},15,[517,666,643],{"class":523},[517,668,669],{"class":646}," TIMEOUT_MS",[517,671,650],{"class":523},[517,673,674],{"class":646}," 10_000",[517,676,602],{"class":527},[517,678,680],{"class":519,"line":679},16,[517,681,682],{"class":608},"\u002F** The most objects Stripe returns per list request. *\u002F\n",[517,684,686,688,691,693,696],{"class":519,"line":685},17,[517,687,643],{"class":523},[517,689,690],{"class":646}," PAGE_SIZE",[517,692,650],{"class":523},[517,694,695],{"class":646}," 100",[517,697,602],{"class":527},[517,699,701],{"class":519,"line":700},18,[517,702,703],{"class":608},"\u002F** Stripe ids are letters, digits, `_` and `-`. Anything else can't name an object. *\u002F\n",[517,705,707,709,712,714,717,720,723,726,729,732],{"class":519,"line":706},19,[517,708,643],{"class":523},[517,710,711],{"class":646}," STRIPE_ID",[517,713,650],{"class":523},[517,715,716],{"class":598}," \u002F",[517,718,719],{"class":523},"^",[517,721,722],{"class":646},"[\\w-]",[517,724,725],{"class":523},"+$",[517,727,728],{"class":598},"\u002F",[517,730,731],{"class":523},"u",[517,733,602],{"class":527},[517,735,737],{"class":519,"line":736},20,[517,738,739],{"class":608},"    \u002F\u002F …\n",[517,741,743],{"class":519,"line":742},21,[517,744,745],{"class":608},"    \u002F** Sends one request and reads the whole body within the deadline. Throws only when no answer arrives. *\u002F\n",[517,747,749,752,755,758,761,764,767,770,773,776,778,781,783,786,789,792,795,799,802,805,808],{"class":519,"line":748},22,[517,750,751],{"class":534},"    async",[517,753,754],{"class":527}," #",[517,756,757],{"class":646},"send",[517,759,760],{"class":527},"(",[517,762,763],{"class":534},"method",[517,765,766],{"class":527},": ",[517,768,769],{"class":534},"Method",[517,771,772],{"class":527},", ",[517,774,775],{"class":534},"path",[517,777,766],{"class":527},[517,779,780],{"class":534},"string",[517,782,772],{"class":527},[517,784,785],{"class":534},"form",[517,787,788],{"class":523},"?:",[517,790,791],{"class":534}," URLSearchParams",[517,793,794],{"class":527},"): ",[517,796,798],{"class":797},"snHjA","Promise",[517,800,801],{"class":523},"\u003C",[517,803,804],{"class":534},"StripeResponse",[517,806,807],{"class":523},">",[517,809,528],{"class":527},[517,811,813,816,819,821,823,826,829,831,834,837,839,842,845,847,850,852,854],{"class":519,"line":812},23,[517,814,815],{"class":527},"        const headers: ",[517,817,818],{"class":534},"Record",[517,820,801],{"class":523},[517,822,780],{"class":534},[517,824,825],{"class":527},", string> = { ",[517,827,828],{"class":598},"'Authorization'",[517,830,766],{"class":527},[517,832,833],{"class":598},"`Bearer ${",[517,835,836],{"class":646},"this",[517,838,471],{"class":598},[517,840,841],{"class":534},"#apiKey",[517,843,844],{"class":598},"}`",[517,846,772],{"class":527},[517,848,849],{"class":598},"'Stripe-Version'",[517,851,766],{"class":527},[517,853,620],{"class":646},[517,855,856],{"class":527}," };\n",[517,858,860,863,866,868,870,872,874,877,880,883,885,888,890,893],{"class":519,"line":859},24,[517,861,862],{"class":527},"        const init: ",[517,864,865],{"class":534},"RequestInit",[517,867,650],{"class":523},[517,869,617],{"class":527},[517,871,763],{"class":534},[517,873,772],{"class":527},[517,875,876],{"class":534},"headers",[517,878,879],{"class":527},", signal: ",[517,881,882],{"class":534},"AbortSignal",[517,884,471],{"class":527},[517,886,887],{"class":646},"timeout",[517,889,760],{"class":527},[517,891,892],{"class":646},"TIMEOUT_MS",[517,894,895],{"class":527},") };\n",[517,897,899],{"class":519,"line":898},25,[517,900,637],{"emptyLinePlaceholder":636},[517,902,904,907,910,912,915,918],{"class":519,"line":903},26,[517,905,906],{"class":646},"        if",[517,908,909],{"class":527}," (",[517,911,785],{"class":534},[517,913,914],{"class":523}," !==",[517,916,917],{"class":646}," undefined",[517,919,920],{"class":527},") {\n",[517,922,924,927,930],{"class":519,"line":923},27,[517,925,926],{"class":527},"            headers[",[517,928,929],{"class":598},"'Content-Type'",[517,931,932],{"class":527},"] = 'application\u002Fx-www-form-urlencoded';\n",[517,934,936],{"class":519,"line":935},28,[517,937,938],{"class":527},"            init.body = form.toString();\n",[517,940,942],{"class":519,"line":941},29,[517,943,944],{"class":527},"        }\n",[517,946,948],{"class":519,"line":947},30,[517,949,637],{"emptyLinePlaceholder":636},[517,951,953,956,959],{"class":519,"line":952},31,[517,954,955],{"class":527},"        let response: ",[517,957,958],{"class":534},"Response",[517,960,602],{"class":527},[517,962,964,967,970,972,974],{"class":519,"line":963},32,[517,965,966],{"class":534},"        let",[517,968,969],{"class":534}," text",[517,971,766],{"class":527},[517,973,780],{"class":534},[517,975,602],{"class":527},[517,977,979],{"class":519,"line":978},33,[517,980,637],{"emptyLinePlaceholder":636},[517,982,984,987],{"class":519,"line":983},34,[517,985,986],{"class":534},"        try",[517,988,528],{"class":527},[517,990,992,995,997,1000,1003,1005,1008,1011,1013,1015,1017,1020,1023,1026],{"class":519,"line":991},35,[517,993,994],{"class":534},"            response",[517,996,650],{"class":523},[517,998,999],{"class":523}," await",[517,1001,1002],{"class":646}," fetch",[517,1004,760],{"class":527},[517,1006,1007],{"class":523},"new",[517,1009,1010],{"class":646}," URL",[517,1012,760],{"class":527},[517,1014,775],{"class":534},[517,1016,772],{"class":527},[517,1018,1019],{"class":646},"BASE_URL",[517,1021,1022],{"class":527},"), ",[517,1024,1025],{"class":534},"init",[517,1027,1028],{"class":527},");\n",[517,1030,1032,1035,1037,1039,1042,1044,1047],{"class":519,"line":1031},36,[517,1033,1034],{"class":534},"            text",[517,1036,650],{"class":523},[517,1038,999],{"class":523},[517,1040,1041],{"class":534}," response",[517,1043,471],{"class":527},[517,1045,1046],{"class":646},"text",[517,1048,1049],{"class":527},"();\n",[517,1051,1053],{"class":519,"line":1052},37,[517,1054,944],{"class":527},[517,1056,1058,1061,1063,1066],{"class":519,"line":1057},38,[517,1059,1060],{"class":646},"        catch",[517,1062,909],{"class":527},[517,1064,1065],{"class":534},"error",[517,1067,920],{"class":527},[517,1069,1071,1074,1077,1079,1082,1085,1088,1091,1093,1095,1098,1101,1104],{"class":519,"line":1070},39,[517,1072,1073],{"class":527},"            const ",[517,1075,1076],{"class":534},"isTimeout",[517,1078,650],{"class":523},[517,1080,1081],{"class":534}," error",[517,1083,1084],{"class":523}," instanceof",[517,1086,1087],{"class":646}," Error",[517,1089,1090],{"class":523}," &&",[517,1092,1081],{"class":534},[517,1094,471],{"class":527},[517,1096,1097],{"class":534},"name",[517,1099,1100],{"class":523}," ===",[517,1102,1103],{"class":598}," 'TimeoutError'",[517,1105,602],{"class":527},[517,1107,1109,1111,1114,1116,1119,1122,1125,1127,1129,1132,1135,1138,1141],{"class":519,"line":1108},40,[517,1110,1073],{"class":527},[517,1112,1113],{"class":534},"reason",[517,1115,650],{"class":523},[517,1117,1118],{"class":534}," isTimeout",[517,1120,1121],{"class":523}," ?",[517,1123,1124],{"class":598}," `did not answer within ${",[517,1126,892],{"class":646},[517,1128,716],{"class":523},[517,1130,1131],{"class":646}," 1000",[517,1133,1134],{"class":598},"} seconds`",[517,1136,1137],{"class":523}," :",[517,1139,1140],{"class":598}," 'could not be reached'",[517,1142,602],{"class":527},[517,1144,1146],{"class":519,"line":1145},41,[517,1147,1148],{"class":608},"            \u002F\u002F Keep the rejection as the `cause`: when the data source's permissions refused the request,\n",[517,1150,1152],{"class":519,"line":1151},42,[517,1153,1154],{"class":608},"            \u002F\u002F Engine finds that there and reports a permission error instead of a failed connection.\n",[517,1156,1158,1161,1164,1166,1169,1171,1174,1177,1179,1181,1183],{"class":519,"line":1157},43,[517,1159,1160],{"class":527},"            throw new ",[517,1162,1163],{"class":646},"ConnectionFailed",[517,1165,760],{"class":527},[517,1167,1168],{"class":598},"`The Stripe API ${",[517,1170,1113],{"class":534},[517,1172,1173],{"class":598},"}.`",[517,1175,1176],{"class":527},", { ",[517,1178,494],{"class":523},[517,1180,766],{"class":527},[517,1182,1065],{"class":523},[517,1184,1185],{"class":527}," });\n",[517,1187,1189],{"class":519,"line":1188},44,[517,1190,944],{"class":527},[517,1192,1194],{"class":519,"line":1193},45,[517,1195,637],{"emptyLinePlaceholder":636},[517,1197,1199,1202,1205,1208,1210,1213,1216,1218,1220,1223,1226,1229,1231,1233,1236,1238,1240,1242],{"class":519,"line":1198},46,[517,1200,1201],{"class":534},"        return",[517,1203,1204],{"class":527}," { status: ",[517,1206,1207],{"class":534},"response",[517,1209,471],{"class":527},[517,1211,1212],{"class":534},"status",[517,1214,1215],{"class":527},", ok: ",[517,1217,1207],{"class":534},[517,1219,471],{"class":527},[517,1221,1222],{"class":534},"ok",[517,1224,1225],{"class":527},", body: ",[517,1227,1228],{"class":646},"parseJson",[517,1230,760],{"class":527},[517,1232,1046],{"class":534},[517,1234,1235],{"class":527},"), headers: ",[517,1237,1207],{"class":534},[517,1239,471],{"class":527},[517,1241,876],{"class":534},[517,1243,856],{"class":527},[517,1245,1247],{"class":519,"line":1246},47,[517,1248,1249],{"class":527},"    }\n",[517,1251,1253],{"class":519,"line":1252},48,[517,1254,1255],{"class":527},"}\n",[517,1257,1259],{"class":519,"line":1258},49,[517,1260,637],{"emptyLinePlaceholder":636},[517,1262,1264],{"class":519,"line":1263},50,[517,1265,1266],{"class":608},"\u002F** The body of a successful response; any other response becomes an error. *\u002F\n",[517,1268,1270,1273,1276,1278,1281,1284,1286,1289,1292,1294,1297,1300,1303,1306,1309],{"class":519,"line":1269},51,[517,1271,1272],{"class":523},"function",[517,1274,1275],{"class":646}," checked",[517,1277,760],{"class":527},[517,1279,1280],{"class":523},"response:",[517,1282,1283],{"class":646}," StripeResponse",[517,1285,772],{"class":527},[517,1287,1288],{"class":523},"method:",[517,1290,1291],{"class":646}," Method",[517,1293,772],{"class":527},[517,1295,1296],{"class":523},"path:",[517,1298,1299],{"class":797}," string",[517,1301,1302],{"class":527},")",[517,1304,1305],{"class":523},":",[517,1307,1308],{"class":797}," unknown",[517,1310,528],{"class":527},[517,1312,1314,1317,1319,1322,1324,1326,1328,1331,1334,1337,1339,1341,1343,1345,1347,1349],{"class":519,"line":1313},52,[517,1315,1316],{"class":523},"    if",[517,1318,909],{"class":527},[517,1320,1321],{"class":523},"!",[517,1323,1207],{"class":534},[517,1325,471],{"class":527},[517,1327,1222],{"class":534},[517,1329,1330],{"class":527},") ",[517,1332,1333],{"class":523},"throw",[517,1335,1336],{"class":646}," toConnectorError",[517,1338,760],{"class":527},[517,1340,1207],{"class":534},[517,1342,772],{"class":527},[517,1344,763],{"class":534},[517,1346,772],{"class":527},[517,1348,775],{"class":534},[517,1350,1028],{"class":527},[517,1352,1354],{"class":519,"line":1353},53,[517,1355,1356],{"class":608},"    \u002F\u002F A changed API, not something the caller can fix: a plain error, which Engine reports as a failed query.\n",[517,1358,1360,1362,1364,1366,1368,1371,1373,1375,1377,1379,1382,1384,1386,1389],{"class":519,"line":1359},54,[517,1361,1316],{"class":523},[517,1363,909],{"class":527},[517,1365,1207],{"class":534},[517,1367,471],{"class":527},[517,1369,1370],{"class":534},"body",[517,1372,1100],{"class":523},[517,1374,917],{"class":646},[517,1376,1330],{"class":527},[517,1378,1333],{"class":523},[517,1380,1381],{"class":523}," new",[517,1383,1087],{"class":646},[517,1385,760],{"class":527},[517,1387,1388],{"class":598},"'Stripe returned a response that is not JSON.'",[517,1390,1028],{"class":527},[517,1392,1394,1397,1399,1401,1403],{"class":519,"line":1393},55,[517,1395,1396],{"class":523},"    return",[517,1398,1041],{"class":534},[517,1400,471],{"class":527},[517,1402,1370],{"class":534},[517,1404,602],{"class":527},[517,1406,1408],{"class":519,"line":1407},56,[517,1409,1255],{"class":527},[1411,1412,1413,1447,1463],"ul",{},[1414,1415,1416,1419,1420,1423,1424,1427,1428,1430,1431,1434,1435,1438,1439,1441,1442,471],"li",{},[476,1417,1418],{},"A permission denial survives the wrap."," A ",[464,1421,1422],{},"fetch"," to a host outside the data source's granted permissions rejects with an error named ",[464,1425,1426],{},"NotCapable",". Engine looks for it anywhere in the thrown error's ",[464,1429,494],{}," chain, so wrapped with ",[464,1432,1433],{},"{ cause: error }"," it's still reported as invalid permissions (",[464,1436,1437],{},"2003","), with your message nested inside. Wrapped without ",[464,1440,494],{},", it reads as the wrapping class. See ",[1443,1444,1446],"a",{"href":1445},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fpermissions#handle-a-denied-request","Handle a Denied Request",[1414,1448,1449,1452,1453,1456,1457,1459,1460,471],{},[476,1450,1451],{},"The deadline covers the body."," ",[464,1454,1455],{},"AbortSignal.timeout"," also aborts a body read, so the read sits inside the ",[464,1458,490],{},". A timeout rejects with an error named ",[464,1461,1462],{},"TimeoutError",[1414,1464,1465,1472,1473,1476,1477,1479],{},[476,1466,1467,1468,1471],{},"A body that isn't JSON becomes a plain ",[464,1469,1470],{},"Error",","," with a message the caller can read, not a ",[464,1474,1475],{},"SyntaxError"," from deep inside the parser. No class fits a changed API, and Engine reports the plain ",[464,1478,1470],{}," as a failed query.",[460,1481,1482,1486],{},[1443,1483,1485],{"href":1484},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Ferrors","Handle Data Connector Errors"," walks through how the Stripe client maps each error status to a class.",[460,1488,1489,1490,1493,1494,1496,1497,1501],{},"Every class takes ",[464,1491,1492],{},"(message: string, options?: { cause?: unknown })",". The message is what Engine reports, so write it for the person reading the error, not for yourself. ",[464,1495,494],{}," stays on the JavaScript error, where Engine looks only for a permission denial. Engine receives only the code and the message (see ",[1443,1498,1500],{"href":1499},"#know-what-the-caller-sees","Know What the Caller Sees",").",[460,1503,1504,1505,1508,1509,1512,1513,1516],{},"Engine recognizes an error by its ",[464,1506,1507],{},"monospace"," property, ",[464,1510,1511],{},"{ code }",", not by its class. Two bundled copies of the kit, or a connector without the kit, work the same way: a thrown object whose ",[464,1514,1515],{},"monospace.code"," is a safe integer is read identically. Use the kit's codes. Engine reports a code it doesn't recognize as a failed query.",[455,1518,1520],{"id":1519},"pick-an-error-class","Pick an Error Class",[1522,1523,1524,1540],"table",{},[1525,1526,1527],"thead",{},[1528,1529,1530,1534,1537],"tr",{},[1531,1532,1533],"th",{},"Class",[1531,1535,1536],{},"Code",[1531,1538,1539],{},"Throw when",[1541,1542,1543,1559,1574,1589,1604,1619,1634,1649,1663],"tbody",{},[1528,1544,1545,1551,1556],{},[1546,1547,1548],"td",{},[464,1549,1550],{},"QueryRejected",[1546,1552,1553],{},[464,1554,1555],{},"100",[1546,1557,1558],{},"A valid query or write can't be served as asked (e.g., without a filter the external data source requires, beyond a page window or a read budget, or with a value outside a field's rule). The caller can change the request, so write the message for them",[1528,1560,1561,1566,1571],{},[1546,1562,1563],{},[464,1564,1565],{},"UniqueConstraintViolation",[1546,1567,1568],{},[464,1569,1570],{},"1002",[1546,1572,1573],{},"The external data source rejects a write because a value must be unique",[1528,1575,1576,1581,1586],{},[1546,1577,1578],{},[464,1579,1580],{},"NullConstraintViolation",[1546,1582,1583],{},[464,1584,1585],{},"1003",[1546,1587,1588],{},"The external data source rejects a write because a required value is missing",[1528,1590,1591,1596,1601],{},[1546,1592,1593],{},[464,1594,1595],{},"ForeignKeyConstraintViolation",[1546,1597,1598],{},[464,1599,1600],{},"1004",[1546,1602,1603],{},"The external data source rejects a write because a referenced item doesn't exist, or another item still references it",[1528,1605,1606,1611,1616],{},[1546,1607,1608],{},[464,1609,1610],{},"InvalidConfiguration",[1546,1612,1613],{},[464,1614,1615],{},"2001",[1546,1617,1618],{},"The data source's configuration is missing a value or has a wrong one, found before or without asking the external data source (e.g., a malformed URL or an unknown region)",[1528,1620,1621,1626,1631],{},[1546,1622,1623],{},[464,1624,1625],{},"AccessDenied",[1546,1627,1628],{},[464,1629,1630],{},"2002",[1546,1632,1633],{},"The external data source refuses this account: its credentials are rejected, expired or revoked, lack a scope, can't reach the resource, or exceed the plan",[1528,1635,1636,1641,1646],{},[1546,1637,1638],{},[464,1639,1640],{},"CollectionNotFound",[1546,1642,1643],{},[464,1644,1645],{},"2004",[1546,1647,1648],{},"A collection your connector declared no longer exists in the external data source (e.g., an object type deleted after the data source was introspected). Engine sends only declared collections",[1528,1650,1651,1655,1660],{},[1546,1652,1653],{},[464,1654,1163],{},[1546,1656,1657],{},[464,1658,1659],{},"5001",[1546,1661,1662],{},"The external data source can't be reached, or won't answer for now: a network failure, a timeout, maintenance, or a server error it reports as temporary",[1528,1664,1665,1670,1675],{},[1546,1666,1667],{},[464,1668,1669],{},"RateLimited",[1546,1671,1672],{},[464,1673,1674],{},"5002",[1546,1676,1677,1678],{},"The external data source is throttling the connector: a rate limit, or a quota that resets. For a limit only a plan change lifts, throw ",[464,1679,1625],{},[460,1681,1682,1683,772,1686,772,1689,1692,1693,1696,1697,1700,1701,471],{},"No class reports a missing item. A keyed operation (",[464,1684,1685],{},"readOne",[464,1687,1688],{},"updateOne",[464,1690,1691],{},"deleteOne",") whose key or guard misses answers ",[464,1694,1695],{},"{ record: null }",", which callers see as ",[464,1698,1699],{},"404",". A read that matches nothing answers no items. See ",[1443,1702,1704],{"href":1703},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi#keyed-operations","Keyed Operations",[460,1706,1707,1708,1711,1712,1715,1716,1711,1719,1722,1723,1711,1726,1729,1730,1733],{},"Each code's range says who can fix the failure: ",[464,1709,1710],{},"1"," to ",[464,1713,1714],{},"999"," is invalid input and ",[464,1717,1718],{},"1000",[464,1720,1721],{},"1999"," a failure the caller can fix. ",[464,1724,1725],{},"2000",[464,1727,1728],{},"2999"," needs someone with access to the data source or to the external data source's account, and ",[464,1731,1732],{},"5000"," and up is infrastructure, where a later retry may work.",[460,1735,1736,1737,1740,1741,1744,1745,772,1748,772,1751,772,1754,772,1757,1760,1761,1764],{},"All nine classes extend the abstract ",[464,1738,1739],{},"ConnectorError",". The module also exports the ",[464,1742,1743],{},"ErrorCode"," map, and the ",[464,1746,1747],{},"ErrorCodeName",[464,1749,1750],{},"ShellErrorCodeName",[464,1752,1753],{},"ThrownErrorCode",[464,1755,1756],{},"ThrownErrorCodeName",[464,1758,1759],{},"ConnectorErrorOptions"," and ",[464,1762,1763],{},"ConnectorErrorBrand"," types.",[460,1766,1767,1768,1770,1771,471],{},"For anything no class describes, throw a plain ",[464,1769,1470],{},". Engine reports it as a failed query. The example connectors do this in two cases: a changed API (a successful answer that isn't JSON, has the wrong shape, or holds a value of the wrong type), and a request their declaration never offered. See ",[1443,1772,1774],{"href":1773},"#tell-queryrejected-from-a-plain-error","Tell QueryRejected from a Plain Error",[1776,1777,1779],"h3",{"id":1778},"read-codes-from-errorcode","Read Codes from ErrorCode",[460,1781,1782,1784,1785,1788],{},[464,1783,1743],{}," maps each name to its code, for code that recognizes an error without ",[464,1786,1787],{},"instanceof",", such as a smoke test that drives the built file. Compare with its entries, never with hard-coded numbers. The kit generates it from Engine's own list of codes:",[508,1790,1792],{"className":510,"code":1791,"filename":470,"language":512,"meta":513,"style":513},"export const ErrorCode = {\n    QueryRejected: 100,\n    UniqueConstraintViolation: 1002,\n    NullConstraintViolation: 1003,\n    ForeignKeyConstraintViolation: 1004,\n    InvalidConfiguration: 2001,\n    AccessDenied: 2002,\n    InvalidPermissions: 2003,\n    CollectionNotFound: 2004,\n    ConnectionFailed: 5001,\n    RateLimited: 5002,\n    MethodNotFound: -32_601,\n} as const;\n",[464,1793,1794,1809,1818,1827,1836,1845,1854,1863,1872,1881,1890,1899,1912],{"__ignoreMap":513},[517,1795,1796,1799,1802,1805,1807],{"class":519,"line":520},[517,1797,1798],{"class":523},"export",[517,1800,1801],{"class":523}," const",[517,1803,1804],{"class":646}," ErrorCode",[517,1806,650],{"class":523},[517,1808,528],{"class":527},[517,1810,1811,1814,1816],{"class":519,"line":531},[517,1812,1813],{"class":527},"    QueryRejected: ",[517,1815,1555],{"class":646},[517,1817,538],{"class":527},[517,1819,1820,1823,1825],{"class":519,"line":541},[517,1821,1822],{"class":527},"    UniqueConstraintViolation: ",[517,1824,1570],{"class":646},[517,1826,538],{"class":527},[517,1828,1829,1832,1834],{"class":519,"line":549},[517,1830,1831],{"class":527},"    NullConstraintViolation: ",[517,1833,1585],{"class":646},[517,1835,538],{"class":527},[517,1837,1838,1841,1843],{"class":519,"line":557},[517,1839,1840],{"class":527},"    ForeignKeyConstraintViolation: ",[517,1842,1600],{"class":646},[517,1844,538],{"class":527},[517,1846,1847,1850,1852],{"class":519,"line":565},[517,1848,1849],{"class":527},"    InvalidConfiguration: ",[517,1851,1615],{"class":646},[517,1853,538],{"class":527},[517,1855,1856,1859,1861],{"class":519,"line":573},[517,1857,1858],{"class":527},"    AccessDenied: ",[517,1860,1630],{"class":646},[517,1862,538],{"class":527},[517,1864,1865,1868,1870],{"class":519,"line":581},[517,1866,1867],{"class":527},"    InvalidPermissions: ",[517,1869,1437],{"class":646},[517,1871,538],{"class":527},[517,1873,1874,1877,1879],{"class":519,"line":589},[517,1875,1876],{"class":527},"    CollectionNotFound: ",[517,1878,1645],{"class":646},[517,1880,538],{"class":527},[517,1882,1883,1886,1888],{"class":519,"line":605},[517,1884,1885],{"class":527},"    ConnectionFailed: ",[517,1887,1659],{"class":646},[517,1889,538],{"class":527},[517,1891,1892,1895,1897],{"class":519,"line":612},[517,1893,1894],{"class":527},"    RateLimited: ",[517,1896,1674],{"class":646},[517,1898,538],{"class":527},[517,1900,1901,1904,1907,1910],{"class":519,"line":633},[517,1902,1903],{"class":527},"    MethodNotFound: ",[517,1905,1906],{"class":523},"-",[517,1908,1909],{"class":646},"32_601",[517,1911,538],{"class":527},[517,1913,1914,1916,1919,1921],{"class":519,"line":640},[517,1915,592],{"class":527},[517,1917,1918],{"class":523},"as",[517,1920,1801],{"class":523},[517,1922,602],{"class":527},[460,1924,1925,1926,1929,1930,1933,1934,1936,1937,1939,1940,1943],{},"Only Engine's side of the protocol raises ",[464,1927,1928],{},"InvalidPermissions"," (a permission denial) and ",[464,1931,1932],{},"MethodNotFound"," (a missing handler). The type ",[464,1935,1750],{}," names them. The kit has no class for either, and a class's ",[464,1938,1515],{}," is typed to the nine codes a connector throws. Engine reports a code it doesn't recognize as a failed query: ",[464,1941,1942],{},"500"," \"Failed to query the database\".",[1776,1945,1774],{"id":1946},"tell-queryrejected-from-a-plain-error",[460,1948,1949],{},"Both refuse a request before or instead of answering it. Pick by whose request it is:",[1411,1951,1952,1975],{},[1414,1953,1954,1958,1959,1962,1963,1966,1967,1971,1972,471],{},[476,1955,1956,1305],{},[464,1957,1550],{}," the request fits the declaration, but the external data source can't serve it as asked. That includes shapes Engine composes on its own, whatever the collection declares: ",[464,1960,1961],{},"not"," around an update's field rules, and ",[464,1964,1965],{},"or"," across permission rules. See ",[1443,1968,1970],{"href":1969},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi#handle-requests-you-didnt-declare","Handle Requests You Didn't Declare",". The caller gets ",[464,1973,1974],{},"422",[1414,1976,1977,1982,1983,1985,1986,1943],{},[476,1978,1979,1980,1305],{},"A plain ",[464,1981,1470],{}," the request names something the collection never declared. That's an unknown collection or namespace, an operation, a filter field or operator, a sort, a count, a key other than the declared one, or a write. Nothing the caller changes fixes it, so don't use ",[464,1984,1550],{},", which tells the caller to change the request. The caller gets ",[464,1987,1942],{},[460,1989,1990,1991,1995],{},"Engine checks callers' requests against the data source's stored schema, but not the filters it sends to your connector. So a comparison outside your declaration can come from a permission rule's condition or an ",[1443,1992,1994],{"href":1993},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Fdata-sources#update-data-sources-after-an-extension-update","extension update"," that narrowed the declaration without a schema refresh. Refuse it rather than drop it: a dropped condition can widen what the caller may touch.",[460,1997,1998,1999,471],{},"Some undeclared comparisons are expected: Engine's relation and read-back lookups on a key no declaration can carry. Serve them. See ",[1443,2000,1970],{"href":1969},[1776,2002,2004],{"id":2003},"use-invalidconfiguration-and-accessdenied-for-configuration","Use InvalidConfiguration and AccessDenied for Configuration",[460,2006,2007],{},"Where you throw them decides what happens:",[1411,2009,2010,2021,2032],{},[1414,2011,2012,2017,2018,2020],{},[476,2013,2014,2015,471],{},"From ",[464,2016,466],{}," Engine stops the data source until the extension is reloaded, because a retry can't fix the configuration. The request that started the connector and every later one that reaches it answer ",[464,2019,1974],{}," \"Invalid extension configuration\", with \"the extension is deactivated\" and your message nested inside; results the cache already holds are still served.",[1414,2022,2023,2028,2029,2031],{},[476,2024,2014,2025,471],{},[464,2026,2027],{},"preflight"," It also stops the data source until the extension is reloaded. Throw it there when the configuration ",[464,2030,2027],{}," reads to derive hosts is invalid.",[1414,2033,2034,2043,2044,2046,2047,2050,2051,2053],{},[476,2035,2014,2036,2039,2040],{},[464,2037,2038],{},"query"," or ",[464,2041,2042],{},"testConnection"," (e.g., ",[464,2045,1625],{}," for a ",[464,2048,2049],{},"401"," from the external data source). Engine fails that request only, with ",[464,2052,1974],{}," \"Invalid extension configuration\". The data source keeps running.",[460,2055,2056,2057,2059,2060,2062,2063,2065],{},"Throw ",[464,2058,1610],{}," for a value you can tell is wrong without a request, and ",[464,2061,1625],{}," for credentials the external data source refuses. For a request your connector can't serve, throw ",[464,2064,1550],{},": either configuration class tells the caller to check the configuration, which isn't the problem.",[1776,2067,2069],{"id":2068},"know-what-deactivates-a-data-source","Know What Deactivates a Data Source",[460,2071,2072,2073,2039,2075,2077],{},"A failure in ",[464,2074,466],{},[464,2076,2027],{}," stops the data source until the extension is reloaded only when a retry can't fix it:",[1522,2079,2080,2094],{},[1525,2081,2082],{},[1528,2083,2084,2091],{},[1531,2085,2086,2087,2039,2089],{},"Thrown from ",[464,2088,466],{},[464,2090,2027],{},[1531,2092,2093],{},"Effect",[1541,2095,2096,2107,2120,2134],{},[1528,2097,2098,2104],{},[1546,2099,2100,2039,2102],{},[464,2101,1610],{},[464,2103,1625],{},[1546,2105,2106],{},"Deactivates the data source",[1528,2108,2109,2115],{},[1546,2110,2111,2112,2114],{},"A permission denial, raw or anywhere in the ",[464,2113,494],{}," chain",[1546,2116,2117,2118],{},"Deactivates the data source. From a handler, the same denial fails only that request, with ",[464,2119,1974],{},[1528,2121,2122,2132],{},[1546,2123,2124,2126,2127,2039,2130],{},[464,2125,466],{}," returning no handler object, or handlers without ",[464,2128,2129],{},"introspect",[464,2131,2038],{},[1546,2133,2106],{},[1528,2135,2136,2141],{},[1546,2137,2138,2139],{},"Any other class, or a plain ",[464,2140,1470],{},[1546,2142,2143,2144,2146],{},"Fails that request with ",[464,2145,1974],{}," \"Invalid extension configuration\". The next request tries again",[460,2148,2149,2150,772,2152,2039,2154,2156],{},"Nothing thrown from ",[464,2151,2129],{},[464,2153,2038],{},[464,2155,2042],{}," deactivates a data source. A deactivated data source answers every request that reaches its connector, including the one whose start deactivated it, with the error that deactivated it, and \"the extension is deactivated\" nested inside:",[1522,2158,2159,2169],{},[1525,2160,2161],{},[1528,2162,2163,2166],{},[1531,2164,2165],{},"Reason",[1531,2167,2168],{},"Caller's HTTP status and message",[1541,2170,2171,2193,2207,2229],{},[1528,2172,2173,2188],{},[1546,2174,2175,2039,2177,2179,2180,2039,2182,2184,2185,2187],{},[464,2176,466],{},[464,2178,2027],{}," threw ",[464,2181,1610],{},[464,2183,1625],{},", or ",[464,2186,466],{}," returned no usable handlers",[1546,2189,2190,2192],{},[464,2191,1974],{}," \"Invalid extension configuration\"",[1528,2194,2195,2202],{},[1546,2196,2197,2198,2039,2200],{},"A permission denial in ",[464,2199,466],{},[464,2201,2027],{},[1546,2203,2204,2206],{},[464,2205,1974],{}," \"Invalid extension permissions\"",[1528,2208,2209,2212],{},[1546,2210,2211],{},"The grant doesn't match the permissions the connector requires",[1546,2213,2214,2216,2217,2220,2221,2224,2225],{},[464,2215,1974],{}," \"Invalid extension permissions\", with code ",[464,2218,2219],{},"7001"," and the required set in ",[464,2222,2223],{},"meta.permissions",". See ",[1443,2226,2228],{"href":2227},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fpermissions#change-permissions","Change Permissions",[1528,2230,2231,2237],{},[1546,2232,2233,2234,2236],{},"The connector file fails to load, ",[464,2235,2027],{}," answers something the protocol doesn't define, the entry's extension is no longer installed, or its query capabilities changed",[1546,2238,2239,2242,2243],{},[464,2240,2241],{},"503"," \"Data source is deactivated\". See ",[1443,2244,2246],{"href":2245},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Foperations#when-the-capabilities-change","When the Capabilities Change",[1776,2248,2250],{"id":2249},"know-the-defaults-for-unbranded-throws","Know the Defaults for Unbranded Throws",[460,2252,2253,2254,2256],{},"A thrown value without a ",[464,2255,1507],{}," property gets a code from what it carries:",[1522,2258,2259,2269],{},[1525,2260,2261],{},[1528,2262,2263,2266],{},[1531,2264,2265],{},"Thrown value",[1531,2267,2268],{},"Reported as",[1541,2270,2271,2299,2317],{},[1528,2272,2273,2287],{},[1546,2274,2275,2276,2278,2279,2281,2282,772,2284,2286],{},"A value with a permission denial anywhere in its ",[464,2277,494],{}," chain (e.g., a ",[464,2280,1422],{}," to a host outside the data source's granted permissions), from ",[464,2283,466],{},[464,2285,2027],{}," or a handler",[1546,2288,2289,2290,2292,2293,2295,2296],{},"Invalid permissions (",[464,2291,1437],{},"). This wins over any ",[464,2294,1507],{}," property. See ",[1443,2297,432],{"href":2298},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fpermissions",[1528,2300,2301,2310],{},[1546,2302,2303,2304,772,2306,772,2308,1302],{},"Anything else, from a handler (",[464,2305,2129],{},[464,2307,2038],{},[464,2309,2042],{},[1546,2311,2312,2313,2316],{},"Internal error (",[464,2314,2315],{},"-32603","), a failed query",[1528,2318,2319,2326],{},[1546,2320,2321,2322,2039,2324],{},"Anything else, from ",[464,2323,466],{},[464,2325,2027],{},[1546,2327,2328,2330],{},[464,2329,1974],{}," \"Invalid extension configuration\". It doesn't deactivate the data source",[460,2332,2333,2334,2336,2337,2339,2340,2342,2343,2345,2346,2349],{},"A ",[464,2335,1507],{}," property that is set but has no safe-integer ",[464,2338,464],{}," is reported as an internal error (",[464,2341,2315],{},"), wherever it was thrown. A falsy ",[464,2344,1507],{}," property (e.g., ",[464,2347,2348],{},"null",") counts as none.",[460,2351,2352],{},"Throw a kit class instead of letting a raw error escape, so Engine can tell a rate limit from a rejected credential or an outage.",[455,2354,2356],{"id":2355},"keep-secrets-out-of-messages","Keep Secrets out of Messages",[460,2358,2359,2360,2362],{},"Only the code and the message cross to Engine, and the message reaches the caller in the HTTP error response. Nothing else about the error does: not its ",[464,2361,494],{},", its stack, or any other property.",[1411,2364,2365,2374,2384,2390],{},[1414,2366,2367,2370,2371,2373],{},[476,2368,2369],{},"Never interpolate a credential"," (a key, token, or request header) into a message. When the external data source's own message echoes a credential, replace it. The Stripe client throws ",[464,2372,1625],{}," with a fixed message, \"Stripe rejected the API key (HTTP 401).\", because Stripe's message echoes the key's last characters.",[1414,2375,2376,2379,2380,2383],{},[476,2377,2378],{},"Leave out URLs that identify an account,"," such as Stripe's ",[464,2381,2382],{},"request_log_url",", and never copy a whole response body into a message.",[1414,2385,2386,2389],{},[476,2387,2388],{},"Leave out the query string"," of a request you describe. It can hold the caller's filter values. The Stripe client names the path only: \"Stripe answered HTTP 500 to GET \u002Fv1\u002Fcustomers.\"",[1414,2391,2392,2395],{},[476,2393,2394],{},"Leave out personal data"," from items, such as a customer's email.",[460,2397,2398,2399,2402],{},"See ",[1443,2400,2356],{"href":2401},"\u002Fdeveloper\u002Fextensions\u002Fdata-connectors\u002Ferrors#_6-keep-secrets-out-of-messages"," for the Stripe example.",[455,2404,1500],{"id":2405},"know-what-the-caller-sees",[460,2407,2333,2408,2411,2412,2415],{},[476,2409,2410],{},"caller"," is whoever sent the request to the Monospace API, from an SDK, REST, or Studio. Engine translates each code into its own error before answering. On the REST API, a failed query answers with ",[464,2413,2414],{},"\"message\": \"Query failed\"",". Engine's message for the code is nested inside it, and your message under \"the extension returned an error:\":",[1522,2417,2418,2430],{},[1525,2419,2420],{},[1528,2421,2422,2424,2427],{},[1531,2423,1533],{},[1531,2425,2426],{},"Engine's message",[1531,2428,2429],{},"Caller's HTTP status",[1541,2431,2432,2445,2458,2471,2484,2497,2511,2524,2545,2558,2570,2585],{},[1528,2433,2434,2438,2441],{},[1546,2435,2436],{},[464,2437,1640],{},[1546,2439,2440],{},"Table does not exist",[1546,2442,2443],{},[464,2444,1699],{},[1528,2446,2447,2451,2454],{},[1546,2448,2449],{},[464,2450,1565],{},[1546,2452,2453],{},"Unique constraint failed",[1546,2455,2456],{},[464,2457,1974],{},[1528,2459,2460,2464,2467],{},[1546,2461,2462],{},[464,2463,1580],{},[1546,2465,2466],{},"Null constraint failed",[1546,2468,2469],{},[464,2470,1974],{},[1528,2472,2473,2477,2480],{},[1546,2474,2475],{},[464,2476,1595],{},[1546,2478,2479],{},"Foreign key constraint failed",[1546,2481,2482],{},[464,2483,1974],{},[1528,2485,2486,2490,2493],{},[1546,2487,2488],{},[464,2489,1550],{},[1546,2491,2492],{},"The data source rejected the query",[1546,2494,2495],{},[464,2496,1974],{},[1528,2498,2499,2504,2507],{},[1546,2500,2501,2502,1302],{},"A permission denial (",[464,2503,1437],{},[1546,2505,2506],{},"Invalid extension permissions",[1546,2508,2509],{},[464,2510,1974],{},[1528,2512,2513,2517,2520],{},[1546,2514,2515],{},[464,2516,1163],{},[1546,2518,2519],{},"Failed to connect to the database",[1546,2521,2522,1452],{},[464,2523,1942],{},[1528,2525,2526,2530,2532],{},[1546,2527,2528],{},[464,2529,1669],{},[1546,2531,2519],{},[1546,2533,2534,2536,2537,2540,2541,2544],{},[464,2535,1942],{},", not ",[464,2538,2539],{},"429",", and without a ",[464,2542,2543],{},"Retry-After"," header ",[1528,2546,2547,2551,2554],{},[1546,2548,2549],{},[464,2550,1610],{},[1546,2552,2553],{},"Invalid extension configuration",[1546,2555,2556],{},[464,2557,1974],{},[1528,2559,2560,2564,2566],{},[1546,2561,2562],{},[464,2563,1625],{},[1546,2565,2553],{},[1546,2567,2568],{},[464,2569,1974],{},[1528,2571,2572,2578,2581],{},[1546,2573,2574,2575,1302],{},"A missing handler (",[464,2576,2577],{},"-32601",[1546,2579,2580],{},"Unsupported operation: a protocol method the extension does not implement",[1546,2582,2583],{},[464,2584,1942],{},[1528,2586,2587,2592,2595],{},[1546,2588,1979,2589,2591],{},[464,2590,1470],{},", or a code Engine doesn't recognize",[1546,2593,2594],{},"Failed to query the database",[1546,2596,2597],{},[464,2598,1942],{},[460,2600,2601],{},"The Art Institute connector's refusal of a page past its 1,000-result window answers this way:",[508,2603,2608],{"className":2604,"code":2605,"filename":2606,"language":2607,"meta":513,"style":513},"language-json shiki shiki-themes monospace-light monospace-light monospace-dark","{\n  \"message\": \"Query failed\",\n  \"source\": {\n    \"message\": \"The data source rejected the query\",\n    \"source\": {\n      \"message\": \"the extension returned an error: The Art Institute search API returns only the first 1000 results. Narrow the filter or read an earlier page.\"\n    }\n  }\n}\n","response.json","json",[464,2609,2610,2615,2627,2635,2647,2654,2664,2668,2673],{"__ignoreMap":513},[517,2611,2612],{"class":519,"line":520},[517,2613,2614],{"class":527},"{\n",[517,2616,2617,2620,2622,2625],{"class":519,"line":531},[517,2618,2619],{"class":797},"  \"message\"",[517,2621,766],{"class":527},[517,2623,2624],{"class":598},"\"Query failed\"",[517,2626,538],{"class":527},[517,2628,2629,2632],{"class":519,"line":541},[517,2630,2631],{"class":797},"  \"source\"",[517,2633,2634],{"class":527},": {\n",[517,2636,2637,2640,2642,2645],{"class":519,"line":549},[517,2638,2639],{"class":797},"    \"message\"",[517,2641,766],{"class":527},[517,2643,2644],{"class":598},"\"The data source rejected the query\"",[517,2646,538],{"class":527},[517,2648,2649,2652],{"class":519,"line":557},[517,2650,2651],{"class":797},"    \"source\"",[517,2653,2634],{"class":527},[517,2655,2656,2659,2661],{"class":519,"line":565},[517,2657,2658],{"class":797},"      \"message\"",[517,2660,766],{"class":527},[517,2662,2663],{"class":598},"\"the extension returned an error: The Art Institute search API returns only the first 1000 results. Narrow the filter or read an earlier page.\"\n",[517,2665,2666],{"class":519,"line":573},[517,2667,1249],{"class":527},[517,2669,2670],{"class":519,"line":581},[517,2671,2672],{"class":527},"  }\n",[517,2674,2675],{"class":519,"line":589},[517,2676,1255],{"class":527},[460,2678,2679,2680,2682],{},"The table covers errors your handlers throw. A request that arrives while another request starts or replaces the connector answers ",[464,2681,2241],{}," \"Data source is restarting\".",[460,2684,2685,2686,2689,2690,2692,2693,2695],{},"A connection test (",[464,2687,2688],{},"POST \u002Fapi\u002F{workspace}\u002Fsources\u002Fdata\u002Ftest",") wraps the messages of a failing ",[464,2691,2042],{}," in \"Failed to connect to data source with the provided configuration\" instead of \"Query failed\". A failure while the connector starts, such as an error thrown from ",[464,2694,466],{},", reads \"The extension could not be started\" instead.",[460,2697,2698],{},"These behaviors don't depend on the status mapping:",[1411,2700,2701,2727,2735,2754,2765,2771,2782,2800],{},[1414,2702,2703,2709,2710,772,2712,2039,2714,2716,2717,2719,2720,2722,2723,2726],{},[476,2704,2705,2706,2708],{},"A keyed miss answers ",[464,2707,1699],{}," \"No record found\"."," When ",[464,2711,1685],{},[464,2713,1688],{},[464,2715,1691],{}," answers ",[464,2718,1695],{},", the REST API answers ",[464,2721,1699],{},". The body is ",[464,2724,2725],{},"{\"message\":\"Query failed\",\"source\":{\"message\":\"No record found\"}}",". It's not an error your connector throws, so no message of yours is involved.",[1414,2728,2729,2732,2733,471],{},[476,2730,2731],{},"An undeclared comparison reaches your connector."," Engine doesn't check the filters it sends against the called member's declaration, so what your connector throws for one decides what the caller sees. See ",[1443,2734,1774],{"href":1773},[1414,2736,2737,2740,2741,2179,2743,2039,2745,2747,2748,2750,2751,471],{},[476,2738,2739],{},"A deactivated data source refuses every request that reaches its connector"," until the extension is reloaded, with the status of the error that deactivated it. A result the cache already holds is still served. This includes the request whose ",[464,2742,466],{},[464,2744,1610],{},[464,2746,1625],{},": the caller sees ",[464,2749,1974],{},", with your message nested inside. See ",[1443,2752,2069],{"href":2753},"#know-what-deactivates-a-data-source",[1414,2755,2756,2759,2760,2762,2763,471],{},[476,2757,2758],{},"A build that changes the query capabilities deactivates existing data sources"," when automatic reloading loads it, with ",[464,2761,2241],{}," until the instance restarts or the workspace is rebuilt. See ",[1443,2764,2246],{"href":2245},[1414,2766,2767,2770],{},[476,2768,2769],{},"Testing a configuration starts a fresh connector."," A connection test or schema preview doesn't reuse a data source's connector, so a failed attempt doesn't block the next one, and neither needs a reload.",[1414,2772,2773,2781],{},[476,2774,2775,2777,2778],{},[464,2776,2042],{}," answering ",[464,2779,2780],{},"{ ok: false }"," is reported as a failed connection.",[1414,2783,2784,2789,2790,2792,2793,2796,2797,2799],{},[476,2785,2786,2787],{},"A connector without ",[464,2788,2042],{}," still creates a data source, and a connection test answers ",[464,2791,1974],{}," code ",[464,2794,2795],{},"7002",", \"The connector does not offer a connection test\". Engine runs ",[464,2798,2042],{},", when you implement it, before it creates a data source or previews its schema.",[1414,2801,2802,2805],{},[476,2803,2804],{},"Keep messages readable."," Engine's own message is generic, and yours carries the specifics. Name the limit and what to change (e.g., \"The Art Institute search API returns only the first 1000 results. Narrow the filter or read an earlier page.\").",[455,2807,2809],{"id":2808},"recognize-errors-engine-raises","Recognize Errors Engine Raises",[460,2811,2812,2813,2815,2816,2819],{},"Engine fails a request with one of these messages when your connector breaks the protocol. For an answer that doesn't fit the protocol or the declared schema (the first four rows), the caller sees ",[464,2814,1942],{}," \"Invalid extension response\", with the message nested inside. A value that doesn't fit an ",[464,2817,2818],{},"int32"," field answers:",[508,2821,2823],{"className":2604,"code":2822,"filename":2606,"language":2607,"meta":513,"style":513},"{\n  \"message\": \"Query failed\",\n  \"source\": {\n    \"message\": \"Invalid extension response\",\n    \"source\": {\n      \"message\": \"The extension returned a record that does not match its declared schema\",\n      \"source\": {\n        \"message\": \"Expected a value matching `Int32`, got a string\"\n      }\n    }\n  }\n}\n",[464,2824,2825,2829,2839,2845,2856,2862,2873,2880,2890,2895,2899,2903],{"__ignoreMap":513},[517,2826,2827],{"class":519,"line":520},[517,2828,2614],{"class":527},[517,2830,2831,2833,2835,2837],{"class":519,"line":531},[517,2832,2619],{"class":797},[517,2834,766],{"class":527},[517,2836,2624],{"class":598},[517,2838,538],{"class":527},[517,2840,2841,2843],{"class":519,"line":541},[517,2842,2631],{"class":797},[517,2844,2634],{"class":527},[517,2846,2847,2849,2851,2854],{"class":519,"line":549},[517,2848,2639],{"class":797},[517,2850,766],{"class":527},[517,2852,2853],{"class":598},"\"Invalid extension response\"",[517,2855,538],{"class":527},[517,2857,2858,2860],{"class":519,"line":557},[517,2859,2651],{"class":797},[517,2861,2634],{"class":527},[517,2863,2864,2866,2868,2871],{"class":519,"line":565},[517,2865,2658],{"class":797},[517,2867,766],{"class":527},[517,2869,2870],{"class":598},"\"The extension returned a record that does not match its declared schema\"",[517,2872,538],{"class":527},[517,2874,2875,2878],{"class":519,"line":573},[517,2876,2877],{"class":797},"      \"source\"",[517,2879,2634],{"class":527},[517,2881,2882,2885,2887],{"class":519,"line":581},[517,2883,2884],{"class":797},"        \"message\"",[517,2886,766],{"class":527},[517,2888,2889],{"class":598},"\"Expected a value matching `Int32`, got a string\"\n",[517,2891,2892],{"class":519,"line":589},[517,2893,2894],{"class":527},"      }\n",[517,2896,2897],{"class":519,"line":605},[517,2898,1249],{"class":527},[517,2900,2901],{"class":519,"line":612},[517,2902,2672],{"class":527},[517,2904,2905],{"class":519,"line":633},[517,2906,1255],{"class":527},[460,2908,2909,2910,1305],{},"The two messages about missing handlers carry code ",[464,2911,2577],{},[1522,2913,2914,2924],{},[1525,2915,2916],{},[1528,2917,2918,2921],{},[1531,2919,2920],{},"Message",[1531,2922,2923],{},"Cause",[1541,2925,2926,2949,2964,2974,2997,3017,3027,3042],{},[1528,2927,2928,2935],{},[1546,2929,2930,2931,2934],{},"Missing selected field ",[464,2932,2933],{},"\u003Cfield>",". A record must carry every selected field, using an explicit null where it has no value",[1546,2936,2937,2938,2941,2942,2945,2946],{},"An item in ",[464,2939,2940],{},"records",", or a keyed answer's ",[464,2943,2944],{},"record",", lacks a field listed in ",[464,2947,2948],{},"select",[1528,2950,2951,2961],{},[1546,2952,2953,2954,2957,2958],{},"Expected a value matching ",[464,2955,2956],{},"\u003CType>",", got a ",[464,2959,2960],{},"\u003Ckind>",[1546,2962,2963],{},"A value doesn't fit its field's declared type",[1528,2965,2966,2969],{},[1546,2967,2968],{},"Expected an array for a list-typed field",[1546,2970,2971,2972],{},"A list field's value isn't an array or ",[464,2973,2348],{},[1528,2975,2976,2985],{},[1546,2977,2978,2981,2982],{},[464,2979,2980],{},"\u003Chandler>"," answered with something this protocol does not define: ",[464,2983,2984],{},"\u003Cdetail>",[1546,2986,2987,2988,2990,2991,2993,2994,2996],{},"An answer has a key or a shape the protocol doesn't define. A keyed operation that answers ",[464,2989,2940],{}," reads \"unknown field ",[464,2992,2940],{},", expected ",[464,2995,2944],{},"\"",[1528,2998,2999,3004],{},[1546,3000,3001,3003],{},[464,3002,2980],{}," returned no value",[1546,3005,3006,3007,2039,3010,3012,3013,2536,3015],{},"A handler returned ",[464,3008,3009],{},"undefined",[464,3011,2348],{},". A keyed miss answers ",[464,3014,1695],{},[464,3016,2348],{},[1528,3018,3019,3022],{},[1546,3020,3021],{},"preflight must answer synchronously",[1546,3023,3024,3026],{},[464,3025,2027],{}," returned a promise",[1528,3028,3029,3032],{},[1546,3030,3031],{},"setup did not return a handler object",[1546,3033,3034,3036,3037,2039,3039,3041],{},[464,3035,466],{}," returned something other than an object. It fails at startup and stops the data source until the extension reloads, as a missing ",[464,3038,2129],{},[464,3040,2038],{}," handler does",[1528,3043,3044,3051],{},[1546,3045,3046,3047,3050],{},"the connector returned no ",[464,3048,3049],{},"\u003Chandlers>"," handler",[1546,3052,3053,3055,3056,2039,3058,3060],{},[464,3054,466],{}," returned handlers without ",[464,3057,2129],{},[464,3059,2038],{},". The message lists each missing one (e.g., \"the connector returned no introspect, query handler\")",[460,3062,3063],{},"The answer checks run after your handler returns, so a write your connector already made stays applied when its answer fails them.",[455,3065,3067],{"id":3066},"see-also","See Also",[1411,3069,3070,3075,3081,3086],{},[1414,3071,3072,3074],{},[1443,3073,1485],{"href":1484},": map failures of the external data source to error classes, step by step",[1414,3076,3077,3080],{},[1443,3078,410],{"href":3079},"\u002Freference\u002Fextensions\u002Fdata-connectors\u002Fapi",": handlers, the query wire format, and the answers Engine expects",[1414,3082,3083,3085],{},[1443,3084,432],{"href":2298},": the permission errors a data source can hit",[1414,3087,3088,3091],{},[1443,3089,148],{"href":3090},"\u002Fdeveloper\u002Fapi\u002Ferrors",": the error response shape callers receive from the Monospace API",[3093,3094,3095],"style",{},"html pre.shiki code .sLVBU, html code.shiki .sLVBU{--shiki-light:#0891B2;--shiki-default:#0891B2;--shiki-dark:#22D3EE}html pre.shiki code .sTMul, html code.shiki .sTMul{--shiki-light:#1F2937;--shiki-default:#1F2937;--shiki-dark:#94A3B8}html pre.shiki code .sNJ9c, html code.shiki .sNJ9c{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#E2E8F0}html pre.shiki code .suKVh, html code.shiki .suKVh{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#F8FAFC}html pre.shiki code .seNfP, html code.shiki .seNfP{--shiki-light:#64748B;--shiki-default:#64748B;--shiki-dark:#94A3B8}html pre.shiki code .ssBNi, html code.shiki .ssBNi{--shiki-light:#1659E9;--shiki-default:#1659E9;--shiki-dark:#94B3F5}html pre.shiki code .snHjA, html code.shiki .snHjA{--shiki-light:#124BC4;--shiki-default:#124BC4;--shiki-dark:#5B8EF4}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":513,"searchDepth":531,"depth":531,"links":3097},[3098,3099,3106,3107,3108,3109],{"id":457,"depth":531,"text":458},{"id":1519,"depth":531,"text":1520,"children":3100},[3101,3102,3103,3104,3105],{"id":1778,"depth":541,"text":1779},{"id":1946,"depth":541,"text":1774},{"id":2003,"depth":541,"text":2004},{"id":2068,"depth":541,"text":2069},{"id":2249,"depth":541,"text":2250},{"id":2355,"depth":531,"text":2356},{"id":2405,"depth":531,"text":1500},{"id":2808,"depth":531,"text":2809},{"id":3066,"depth":531,"text":3067},"Reference for the error classes a data connector extension throws, their codes, and how Engine treats and reports each one.","md",null,{},{"title":148,"icon":420},{"title":447,"description":3110},"e9JSbJkbfxsnTAkSfkRWGMVigfn_yREy1Pc19xLtzTE",[3118,3120],{"title":414,"path":415,"stem":416,"description":3119,"icon":176,"children":-1},"Reference for the operations a data connector collection declares, the filter operators each field type allows, and the rules Engine enforces on a declaration.",{"title":422,"path":423,"stem":424,"description":3121,"icon":425,"children":-1},"Hard numbers and fixed rules for data connector extensions at runtime, and the error or behavior each one produces.",1790840089163]