Troubleshooting & FAQ

When the organization uses Bring your own key, Encatch does not fall back to built-in AI and does not consume Encatch AI credits. If the provider is down, out of credit, or the key is revoked, the capability that needs that connection does not run until you fix it or an organization admin switches back to Encatch-managed AI.

What you see depends on the feature:

• Dashboard features such as the AI form builder, External Insights chat, topic categorisation, translation, and sample data fail or stop updating.
• Refine text is hidden in the SDK when AI cannot run.
• Destination AI filter (Jev engine) does not run unless it has a working Vercel AI Gateway connection.

You see an error when a Test fails in Settings → Global Settings → AI Provider. Destination AI filters can still use Default Forward on Error so feedback is not dropped if a filter call fails.

• Check the key was pasted in full, with no spaces before or after it.
• Make sure the key is active in your provider's console and has access to the selected model.
• Make sure billing is enabled on your provider account. New accounts often need a payment method before the API works.
• Confirm the Model ID matches the provider (use gateway ids for Vercel AI Gateway).
• After rotating a key, edit the connection with the new secret, test, then Save project settings. Revoke the old provider key only after tests pass.

• Verify the API key is active and has permission for the chosen model.
• Confirm the Model ID matches the provider (gateway ids for Vercel AI Gateway).
• Check the provider status page and your network allowlist.
• Ensure the model supports the capability requirements (for example structured output or streaming). See Which features use your provider.

• Open the project and go to Settings → Global Settings → AI Provider. Confirm a connection exists and is set as the project default, or as an Override on that capability.
• Click Test on the connection or on the capability row.
• Check your provider account for an exhausted quota, a spending limit, or a revoked key.
• Check your provider's status page for an outage.
• If the organization is on Bring your own key and this project has no working configuration, AI features in that project stay off. They do not fall back to Encatch AI.
• If the provider looks fine, contact Encatch support.

• Check your provider's rate limits. High feedback volumes can hit them, especially during large topic categorisation or External Insights chat runs.
• Raise the limit with your provider, or try again later.
• If Retries on a bad answer is set on an override, Encatch may call the model again when output is broken JSON or a required tool call is missing. Each retry is another paid provider request and adds latency. Adjust or clear retries in the capability override.

Different models phrase summaries and themes differently. This is expected and doesn't mean data is missing. Insights and themes already stored in Encatch stay as they are; new runs use the new configuration.

• Confirm the organization is on Bring your own key under Manage Org & Projects → Settings → AI settings. Encatch AI credits apply only when the organization uses Encatch-managed AI.
• Confirm this project has a saved connection and a default (or override) that Tests successfully. A missing or failing connection does not fall back to built-in AI, so those features do not consume credits either.
• While a capability runs on your connection, Encatch does not deduct AI credits for it. Your provider bills you for that usage.
• Analyse with your AI and the Encatch MCP server always use your own AI tool, not Encatch AI credits.

Growth and Enterprise.

No. While Bring your own key is on and a capability runs on your connection, Encatch AI features don't consume Encatch AI credits. Your provider bills you for usage directly.

All of them, once a connection is configured for the capability: Destination AI filter, Destination AI filter (Jev engine), Refine text, Feedback Q&A, topic categorisation, translation, sample data, the AI form builder, and External Insights chat. See Which features use your provider.

Yes. Bring your own key is an organization setting: every project must use your own connections rather than Encatch's built-in AI. Connections and capability mapping are project-level, so each project can use a different provider, and one project can point different capabilities at different connections.

No. Keys are write-only and encrypted when saved, so no one can view them in Encatch, including admins. To change a key, replace it.

No. Encatch doesn't keep the requests or raw responses. Results you see in Encatch, such as themes and summaries, are saved with your survey data. See Data handling and security.

No. This is configured in the Encatch dashboard. There are no SDK changes.

Encatch does not fall back to built-in AI. The affected features stop until you fix the connection or switch the organization back to Encatch-managed AI.

Yes, at any time. An organization admin switches from Bring your own key to Encatch-managed AI under Manage Org & Projects → Settings → AI settings. Removing a project connection alone does not turn built-in AI back on. See Go back to Encatch's built-in AI.

If Retries on a bad answer is set on an override, Encatch may call the model again when output is broken JSON or a required tool call is missing. Each retry is another paid provider request. Adjust or clear retries in the capability override.