Skip to main content

Test connection

Every installed integration has a Test button in Admin > Integrations (/admin/integrations). Use it after you install or change an integration, and whenever an integration shows Failed. Testing needs integrations:write.

The test runs four steps in order and shows the result of each one, with a short hint when a step fails. Steps after a failed one show Not checked.

StepWhat it checks
Settings and credentialsEvery required setting and secret is filled in, and the other system accepts the credentials. Nothing is sent while a required value is missing.
Reaching the serviceThe other system answered over HTTPS within 15 seconds.
Reading dataA harmless read with the stored credentials worked (for example looking up a number nobody has, or reading the account profile). The test never creates, changes or deletes anything.
AI tools (dry run)Every AI agent tool you allowed for this integration is still offered and can be filled in by the agent. The tools are checked, not run, so nothing changes in the other system. Shows Not checked when no tool is allowed.

When every step passes, the integration becomes Active. When a step fails, it becomes Failed, the integration's error code is kept on the list and an integration.failed event is sent to your webhooks.

What the hints mean​

HintWhat to do
Fill in every required field and secretOpen Configure, fill in the missing values, save and test again.
A setting is not valid for this serviceA value such as the account, shop, domain or instance name does not match what the service expects. Check it in Configure.
The service refused the credentialsCreate a new API key or token in the other system and paste it in Configure. Old keys stop working when they are revoked or rotated.
The sign-in expired or was revokedPress Reconnect to sign in to the other system again (OAuth integrations, see OAuth connections).
The account has no access to this dataGive the key or app the permissions listed for this integration in the connector index.
The service did not answerCheck that this server can reach the internet over HTTPS (firewall, proxy, DNS) and that the address in the settings is right.
The service is busy or downThe other system is rate limiting or unavailable. Try again in a few minutes.
The read did not workThe service answered but refused or did not understand the read. Check that the account is active and has data, then try again.
An allowed AI tool cannot be usedThe connector no longer offers one of the tools you allowed (for example after an update). Open Configure and save the tool list again.

The test never shows the other system's answer, only a short code such as auth_failed, timeout or http_status. Quote the code when you contact support.

API​

POST /api/v1/integrations/installs/{id}/test answers ok, the first failure's code, and steps: one entry per step with step (credentials, reachability, read, tools), status (ok, failed, skipped), code, hint and, for the tools step, the tools that were checked.

{
"ok": false,
"code": "auth_failed",
"steps": [
{"step": "credentials", "status": "failed", "code": "auth_failed", "hint": "check_credentials", "tools": []},
{"step": "reachability", "status": "skipped", "code": null, "hint": null, "tools": []},
{"step": "read", "status": "skipped", "code": null, "hint": null, "tools": []},
{"step": "tools", "status": "skipped", "code": null, "hint": null, "tools": []}
],
"install": {"id": "0199b5a2-6c1e-7d3a-9f00-3c8e1b2a4d78", "status": "failed", "last_error": "auth_failed"}
}

The hint ids are fill_required, check_settings, check_credentials, reconnect, check_permissions, check_network, try_later, check_account and update_tools.