# Troubleshoot integrations

Source: https://kirora.io/docs/guides/integrations/troubleshoot-integrations

Fix a failing Stripe connection, tool calls that are refused, webhook deliveries that fail and AI apps that stop working.

Most integration problems show their cause in the dashboard: on the integration's card under **Integrations**, on its page, in **Developer › Webhooks** or in the **Request log**. Start with the symptom below. Only admins, developers and the owner can see integrations, keys and webhooks.

## An integration shows Failing

Each card under **Integrations** shows whether it's **Connected**, **Failing** or **Not connected**. A failing card says what went wrong in plain words. Admins, developers and the owner also get a notification when a working connection starts failing.

| What the card says | What to do |
| --- | --- |
| *A webhook arrived that your credentials do not sign: connect the current ones* | Your Stripe key was probably changed or rolled in Stripe. Open **Integrations › Stripe**, choose **Replace key** and paste the current secret key. |
| *The plan no longer includes integrations* | The workspace moved to a plan without integrations, so Stripe's payments are refused. Stripe retries a refused payment for a few days, so payments from that time can still arrive if you upgrade soon. See [Plans and billing](https://kirora.io/docs/guides/account/plans-and-billing). |
| *An event could not be recorded; the provider will send it again* | Usually a brief problem on Kirora's side. Stripe resends the payment, and the card clears once one comes through. |
| *A webhook endpoint is not accepting events; check it and turn it back on* | A tool such as Zapier, Make or n8n subscribed an endpoint that keeps failing or was turned off. See [Webhook deliveries fail](#webhook-deliveries-fail). |

On the Stripe page, the same problem shows above **Connection**, with when it happened. A new key clears it.

## Stripe won't connect

The **Secret key** field and the message after **Connect Stripe** say what's wrong:

- *That's a publishable key. Use the secret key; it starts sk_.* You pasted the key that starts `pk_`. In Stripe, go to **Developers › API keys** and copy the secret key instead.
- *Use a Stripe secret key (sk_… or rk_…)* The value isn't a complete secret or restricted key. Copy it again, without spaces.
- *does not accept these credentials; copy them again* Stripe refused the key: it may be revoked, mistyped or from another account.
- *This Stripe key lacks the Webhook Endpoints: Write permission; give the restricted key that permission, or use a secret key* Kirora uses that permission to set up the connection in your Stripe account. Add it to the restricted key in Stripe, or paste a secret key instead.
- *Stripe could not be reached just now; try again in a minute* Stripe didn't answer. Try again shortly.

On the Free plan, the page offers an upgrade instead of the form. Stripe is available on Starter and above.

## Stripe payments aren't showing

Open **Integrations › Stripe** and check **Last payment received**.

- **Only successful payments arrive.** Each becomes an **Order Completed** event. Refunds, failed payments and disputes don't.
- **The payment needs an email address.** Kirora matches the payer by the billing email, or the receipt email. A payment with neither is skipped.
- **New payers have no marketing consent.** They're added as contacts, but your marketing email only reaches people who agreed to it.
- **Payments made before you connected** aren't brought in.

After **Disconnect**, the key is deleted and Stripe's payments are refused. Events already recorded stay.

## A tool's or your app's calls are refused

On a tool's page under **Integrations**, such as **Zapier** or **HTTP API**, **Recent calls** lists what its keys asked for over the last 30 days, and its card shows the number of errors today. For any key, go to **Developer › API keys**, choose **View requests** on its row, and set **Show** to **Errors only**. Each request has a **Request ID** to quote to support.

The common errors:

| Error | What it means | What to do |
| --- | --- | --- |
| `UNAUTHORIZED` (401) | The key is missing, mistyped, revoked or expired | Check the key's **Status** in **Developer › API keys**. Create a new key if it's **Revoked** or **Expired**. |
| `SCOPE_MISSING` (403) | The key doesn't have the permission this call needs | A key's permissions can't be changed. Create a key with the permission, then revoke the old one. |
| `API_KEY_IP_NOT_ALLOWED` (403) | The call came from an address the key doesn't allow | Add the address under **Where it can be used**, or call from an allowed server. |
| `AGENT_KEY_REFUSED` (403) | An agent key tried something only a person can do, such as sending | Do it in the dashboard, or approve the agent's work in **Developer › Agent review**. |
| `PLAN_FEATURE_UNAVAILABLE` (403) | The plan doesn't include this. The message names what's missing, such as *Goals and conversion goals: not included in your plan* | Keys made for Zapier, Make, n8n or Segment, and Goals, need Starter and above. |
| `PLAN_LIMIT_REACHED` (403) | The plan's allowance for the month is used up, such as its tracked events | Events are refused until next month or until the prepaid balance can pay for them; see [Sending past your plan](https://kirora.io/docs/guides/account/plans-and-billing#sending-past-your-plan). Moving up a plan raises the allowance. |
| `RATE_LIMITED` (429) | Too many calls at once | Wait the number of seconds in `Retry-After`, then retry. |

Your developer can look up every code in the [errors reference](https://kirora.io/docs/api/reference/errors).

A tool counts as connected once one of its keys has made a call, so a new key with no calls leaves its card **Not connected**.

## Webhook deliveries fail

Go to **Developer › Webhooks** and read **Recent deliveries**. Each failed delivery shows your server's **Response**. Choose **Details** to see what Kirora sent and what your server replied.

| Response | Likely cause |
| --- | --- |
| *HTTP 401* or *HTTP 403* | Your server rejected the signature. Check it uses the endpoint's current signing secret. After **Rotate secret**, the old one works for 24 hours only. |
| *HTTP 404* | The URL is wrong, or the route was removed. Choose **Edit** to fix it. |
| *HTTP 500* or another 5xx | Your server failed while handling the event. Check its logs. |
| *No reply within 5 seconds* (*No reply yet* while it's still retrying) | Your server took too long. Reply with a 2xx straight away, then do the slow work afterwards. |
| *fetch failed* with a code such as *ECONNREFUSED* or *ENOTFOUND* | Kirora couldn't reach your server: it's down, or the address or its DNS is wrong. |
| *HTTP 410* | The endpoint said it was removed, so Kirora turned it off. A Zap turned off in Zapier does this. |

Kirora retries failed deliveries, holds back an endpoint that keeps failing and turns off one that's gone; events that happen while it's off aren't sent later. See [Retries and turned-off endpoints](https://kirora.io/docs/guides/integrations/api-keys-and-webhooks#retries-and-turned-off-endpoints).

**Send test event** only works on an **Active** endpoint. Resume a paused one first.

If the endpoint can't be saved: the URL must start with `https://` and point to a public address, and each URL can have only one webhook.

## An AI app stopped working

- **A connected app** stops working when its connection has ended: you disconnected it, an admin, a developer or the owner revoked its key, you left the workspace, or it wasn't used for 30 days. Connect it again. See [Connected apps](https://kirora.io/docs/guides/integrations/connected-apps).
- **An assistant using an agent key** stops when the key is revoked or expires. An admin, a developer or the owner creates a new one. See [Connect Claude, Cursor or another AI assistant](https://kirora.io/docs/guides/kiro-ai/use-kiro-ai-with-claude-or-cursor).
- **The assistant says it can't send.** That's by design: an assistant drafts, and a person approves in **Developer › Agent review**.

## Next steps

- [API keys and webhooks](https://kirora.io/docs/guides/integrations/api-keys-and-webhooks)
- [Connect an integration](https://kirora.io/docs/guides/integrations/connect-an-integration)
- [Errors reference](https://kirora.io/docs/api/reference/errors)