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.
| Step | What it checks |
|---|---|
| Settings and credentials | Every 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 service | The other system answered over HTTPS within 15 seconds. |
| Reading data | A 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
| Hint | What to do |
|---|---|
| Fill in every required field and secret | Open Configure, fill in the missing values, save and test again. |
| A setting is not valid for this service | A 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 credentials | Create 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 revoked | Press Reconnect to sign in to the other system again (OAuth integrations, see OAuth connections). |
| The account has no access to this data | Give the key or app the permissions listed for this integration in the connector index. |
| The service did not answer | Check 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 down | The other system is rate limiting or unavailable. Try again in a few minutes. |
| The read did not work | The 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 used | The 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.