> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyfree.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API and Webhook Problems

> Fix API errors and webhooks that don't arrive or don't run.

## What is this?

Fixes for three things: an **API call** that returns an error, a **webhook automation** (another system calling your automation) that doesn't run, and your own **outbound webhook** (the platform calling your server) that isn't arriving.

## What can I do here?

* Read an API error and fix it
* Make a Receive Webhook automation run
* Make your outbound webhook deliver

## How to use it

### API errors

Every error uses the same shape: `{ "success": false, "error": "...", "message": "..." }`.

| Status | `error` | What it means | What to do |
| - | - | - | - |
| `401` | — | Missing or invalid API key | Send the key in the `X-API-Key` or `Authorization: Bearer` header — never in the URL or body. Regenerate it in the Developer Portal if lost |
| `403` | — | The key's owner lacks a permission, or the plan doesn't include the API | Check the **API Access** permission and your plan |
| `403` | `CREDIT_LINE_NOT_ATTACHED` | The WhatsApp number is on credit line billing and the credit line isn't attached | **Channels → WhatsApp → Retry** — see [WhatsApp channel](https://docs.skyfree.io/workspace/channels/whatsapp.md#how-the-channel-is-billed) |
| `402` | `WALLET_EXHAUSTED` | A credit line number has no wallet balance | Recharge in [Transactions](https://docs.skyfree.io/workspace/transactions.md) |
| `422` | `INVALID_COUNTRY_CODE` | The recipient's phone has no valid country code | Send `to` as digits with the country code, for example `919876543210` — [details](https://docs.skyfree.io/troubleshoot/whatsapp/invalid-country-code.md) |
| `429` | — | Rate limited | Wait for the `Retry-After` seconds — see [Rate limits](https://docs.skyfree.io/api-reference/rate-limits.md) |
| `500` | — | The send failed at WhatsApp or the server | Read `message`; for a WhatsApp error see the [Error code reference](https://docs.skyfree.io/troubleshoot/whatsapp/error-codes.md) |

A few send-specific points:

* **Session message** (`whatsapp/message/send`, `…/interactive`, `…/reaction`) works only **within 24 hours of the customer's last message**. Outside that window, send an **approved template** (`whatsapp/templates/send`).
* A template send needs the template **name**, its **language**, and a value for **every** variable — see [Template problems](https://docs.skyfree.io/troubleshoot/whatsapp/template-problems.md).
* If you omit `channelId` the API picks a channel automatically. If you have several, pass the right `channelId` (find it with the channels list endpoint).

### A Receive Webhook automation doesn't run

This is when a form, store or CRM calls your automation's URL — see [Webhooks](https://docs.skyfree.io/workspace/integrations/webhooks.md).

1. Check the automation is **Active**.
2. Check the sender posts **JSON** to the **exact** URL shown (including the token).
3. Open the webhook's **Activity** (or the [Automation Report](https://docs.skyfree.io/workspace/automation/automation-report.md) → **Activity**). Every request is listed:
   * **Processed** — it ran.
   * **Failed** — open it and read the reason. A missing or invalid **phone number** is the most common cause (see [Invalid country code](https://docs.skyfree.io/troubleshoot/whatsapp/invalid-country-code.md)).
   * **Duplicate** — the sender retried; the repeat is ignored on purpose.
4. If you turned on a **secret**, the sender must sign the **raw body exactly as sent** and include the `sha256=` prefix.
5. Nothing listed at all? The request isn't reaching the platform — recheck the URL and that the sender isn't blocked by a firewall.

### Your outbound webhook isn't arriving

This is **Settings → Outbound Webhook**, where the platform sends your channel's messages and delivery updates to your server — see [Outbound Webhook](https://docs.skyfree.io/workspace/settings/outbound-webhook.md).

1. Open the channel type's tab and read **Last delivery**. It says *Delivered. Your server answered 200.* or *Failed.* with the reason.
2. The URL must start with **https\://** and be reachable from the internet (public addresses only).
3. Your server must answer with a **2xx** status within 10 seconds. The platform tries up to 3 times.
4. Check **Send messages** is on and the webhook is saved.
5. Click **Send a test** to see the status and response time straight away.
6. If signature checks fail on your side, sign the raw body with `<timestamp>.` in front, using the secret you saved — a secret is shown once, so generate a new one if you lost it.

## Troubleshooting / Technical Notes

* **I get a 401 right after generating a key.** Copy the whole key and send it as a header; a trailing space or quote breaks it.
* **Too many failed attempts.** Invalid keys are limited per IP address before anything else runs.
* **My automation ran but the WhatsApp message didn't send.** The webhook worked — look at the message's failure reason: [Message failed to send](https://docs.skyfree.io/troubleshoot/whatsapp/message-failed.md).
* **Webhook shows "Failed" for every request.** Open one — the reason (missing data, bad signature) is the same for all of them.

## Related docs

* [Troubleshoot overview](https://docs.skyfree.io/troubleshoot/overview.md)
* [Errors](https://docs.skyfree.io/api-reference/errors.md)
* [Rate limits](https://docs.skyfree.io/api-reference/rate-limits.md)
* [Webhooks](https://docs.skyfree.io/workspace/integrations/webhooks.md)
* [Outbound Webhook](https://docs.skyfree.io/workspace/settings/outbound-webhook.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.