---
title: "Troubleshooting"
description: "Start from what you see, a failing call, a campaign that will not open or a missing webhook, and find the cause and the fix in a few lines."
canonical: https://www.charitips.com/docs/api-reference/troubleshooting
---

# Troubleshooting

> Start from what you see, a failing call, a campaign that will not open or a missing webhook, and find the cause and the fix in a few lines.

Each entry starts from what you see. For the full list of errors of an endpoint, see [Errors](https://www.charitips.com/docs/api-reference/errors.md) or the endpoint's own page.

## Authentication

### Calls start failing with `401` after working for a while

**Cause**: the access token expired. It lasts one hour.

**Fix**: create a new token and retry once. Keep the token in memory or a shared cache and renew it on the first `401`. The token endpoint is meant to be called once an hour, not before each call. See [Authentication](https://www.charitips.com/docs/get-started/authentication.md).

### Creating a token answers `401 Invalid credentials`

**Cause**: the client id or secret is wrong, or belongs to the other environment.

**Fix**: send `test_` credentials to `api.sandbox.charitips.com` and `live_` credentials to `api.charitips.com`, as Basic authentication (`-u id:secret` with cURL).

### Creating a token answers `401 Unauthorized`

**Cause**: the request has no Basic authentication header, or sends a Bearer token instead.

**Fix**: send the client id and secret as Basic authentication. See [Create a token](https://www.charitips.com/docs/api-reference/create-token.md).

### Calls answer `403 Account not active`, `Account not validated` or `Account closed`

**Cause**: the account has not finished its onboarding, or it is closed.

**Fix**: finish the onboarding in the dashboard. For a closed account, [contact us](https://www.charitips.com/contact).

## Campaigns

### Activating a campaign answers `402 NO_ACTIVE_SUBSCRIPTION`

**Cause**: the account billed for the campaign has no active monthly subscription: your (parent) account, or the child account when billed directly by Charitips. The sandbox applies the same rule.

**Fix**: contact us. On the sandbox, an account opened on its own starts with a subscription; for an older test account, ask us to add one. See [Plans and prerequisites](https://www.charitips.com/docs/overview/plans.md).

### Activating a campaign answers `400 No charity selection linked to this campaign`

**Cause**: the campaign has no charities selection.

**Fix**: [create a selection](https://www.charitips.com/docs/api-reference/create-charities-selection.md) with at least one charity, set its id as `charitiesSelectionId` on the campaign, then activate.

### Activating a campaign answers `400 No budget set for this campaign`

**Cause**: the campaign has a fixed budget (`FIXED_AMOUNT`) but no `budget`, which cannot be added after creation.

**Fix**: create the campaign again with its `budget`, in cents, then activate it.

### The campaign stays `PENDING` after activation, or activation answers `403 Campaign is waiting for payment`

**Cause**: the fixed budget was invoiced at activation and the invoice is not paid yet, for example when you pay by bank transfer.

**Fix**: pay the invoice, then activate again. See [List invoices](https://www.charitips.com/docs/api-reference/list-invoices.md).

### A call answers `402 Missing payment method`

**Cause**: the account that pays for the donations has no payment method. Your (parent) account or the child account if they are billed directly.

**Fix**: add one in the [dashboard billing settings](https://app.charitips.com/settings/billing), then retry. On the sandbox, donations skip this check, but paying a fixed budget at activation still needs a test payment method.

### Activation answers `400 Campaign budget exceeds payment card amount limit` or `SEPA Direct Debit amount limit`

**Cause**: the amount to charge is above what your card or SEPA direct debit can take at once. It only happens on live.

**Fix**: create the campaign with a lower budget, or switch to another payment method, such as a bank transfer, in the [dashboard billing settings](https://app.charitips.com/settings/billing).

## Donations and votes

### Creating a donation answers `403 Campaign has to be activated first.`

**Cause**: the campaign is still `DRAFT` or `PENDING`.

**Fix**: [activate the campaign](https://www.charitips.com/docs/api-reference/activate-campaign.md), then retry.

### Creating a donation answers `400 sendingDate is required for EMAIL and SLACK campaigns.`

**Cause**: Charitips sends the donations of this campaign, and needs the date to send each one.

**Fix**: pass `sendingDate`: Charitips sends the donation within ten minutes of it. To send it right away, pass the current time. On a `MANUAL` campaign, leave `sendingDate` out.

### Creating a donation answers `403 Campaign has ended.`

**Cause**: the campaign is `COMPLETE` or `CANCELED`. Nothing can be created, claimed or cast on it.

**Fix**: use an active campaign.

### Creating a donation answers `400 Insufficient campaign budget.`

**Cause**: the donation would take the campaign over its fixed budget.

**Fix**: create a smaller donation, or use another campaign. The API does not raise the budget of an existing campaign.

### Creating a donation answers `400 Campaign is a DISTRIBUTION one. Only votes can be created`

**Cause**: on this campaign, people vote on how a budget is split.

**Fix**: [create a vote](https://www.charitips.com/docs/api-reference/create-vote.md) instead.

### Creating a donation answers `403 Only recurring donations can be created for recurring campaigns.`

**Cause**: the campaign is recurring: its `recurringType` is not `NONE`.

**Fix**: [create a recurring donation](https://www.charitips.com/docs/api-reference/create-recurring-donation.md) on a campaign whose `recurringType` is `FREQUENCY`, or use a campaign whose `recurringType` is `NONE`.

### Creating a donation answers `403 Setting hasBeenCharged, withFiscalReceipt, parentDonationId to another value than the default is only enabled for customers with a B2C use case.`

**Cause**: these fields mean your individual user paid for the donation, which needs the B2C use case on your account. Creating a campaign answers the same for `fiscalReceiptSendingMode`, `withFiscalReceipts` and `defaultHasBeenCharged`, and updating one for the first two.

**Fix**: remove them, or contact us to enable the B2C use case. See [Your users give their own money](https://www.charitips.com/docs/use-cases/b2c.md).

### A `campaignId` you are sure of answers `400 Bad Request`, or an id in the path answers `404`

**Cause**: the id belongs to another account, or to the other environment. An id from the sandbox does not exist on live.

**Fix**: list your campaigns with the same credentials you use for the call, and use an id from that list.

### A retried call answers `409 Unique constraint failed on uniqueExternalId`

**Cause**: your first call succeeded, and the retry sent the same `uniqueExternalId`. That is the protection working.

**Fix**: do not create it again. Fetch the first one with the list endpoint filtered on that id: [donations](https://www.charitips.com/docs/api-reference/list-donations.md), votes or donors. For a recurring donation, keep the id you received at creation.

### Claiming answers `409 Donation already claimed`

**Cause**: the donation is no longer waiting for a charity: your previous claim went through, Charitips assigned it after its expiry date, or it was canceled.

**Fix**: [read the donation](https://www.charitips.com/docs/api-reference/get-donation.md): `status` and `charityId` tell which.

### Deleting a donation answers `403 Donation already invoiced`, `paid` or `processed`

**Cause**: the donation has been invoiced or paid, or its funds have been sent to the charity.

**Fix**: it cannot be deleted any more. Refund your customer in your own books; next time, delete before the donation is billed.

## Fiscal receipts

### A receipt call answers `403 Donor is missing required fiscal information.`

**Cause**: a receipt in the donor's name needs their first name, last name, street, zip, city and country.

**Fix**: complete the donor, or create the donation with `withFiscalReceipt: false`.

### A receipt call answers `403 This charity does not support fiscal receipts.`

**Cause**: not every charity can issue a receipt.

**Fix**: when your user needs a receipt, offer only charities whose `fiscalReceiptsSupport` is `ENABLED`, as returned by [List charities](https://www.charitips.com/docs/api-reference/list-charities.md) and [Get a charity](https://www.charitips.com/docs/api-reference/get-charity.md).

### Getting a receipt answers `404 Fiscal receipt not found.` or `403 Donation has not been processed yet.`

**Cause**: the donation is not processed yet, or its receipt has not been generated.

**Fix**: wait for the `donation_update` webhook, or `fiscalreceipt_generated` for the receipt, then retry. By default receipts are issued once a year. See [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md).

## Webhooks

### No webhook arrives

Check, in this order:

1. **The environment.** A webhook created on the sandbox only receives sandbox events, and a live one live events.
2. **The events.** The webhook only receives the events listed in its `events`, for example `donation_update` for a claim.
3. **The account.** A webhook receives the events of its own account. A parent account's webhooks also receive the events of its child accounts; a child account's webhooks never receive the parent's.
4. **Your endpoint's answer.** Charitips retries the call after `429`, `500`, `502`, `503` or `504`. Any other error status, such as `401`, `403` or `404`, is not retried: check the authentication you gave the webhook (`BASIC` or `BEARER`) and the URL in `target`.

See [Webhooks configuration](https://www.charitips.com/docs/webhooks/configuration.md).

### The same event arrives twice

**Cause**: webhooks are delivered at least once, and internal updates send events too.

**Fix**: make your handler idempotent: store the ids you processed and skip a repeat.

### The signature never matches

**Cause**: the signature is computed on the raw body. A framework that parses the body first changes it. A key from another webhook or environment also fails.

**Fix**: read the raw body, check the signature with that webhook's `signingKey` and the `X-Charitips-Timestamp` header, then parse. The key is shown once, at creation: if it is lost, create a new webhook for the same URL.

### Creating a webhook answers `402 Plan upgrade required`

**Cause**: your plan does not include API access.

**Fix**: contact us to add it. See [Plans and prerequisites](https://www.charitips.com/docs/overview/plans.md).

## Other

### A call answers `402 Plan upgrade required`

**Cause**: the call needs a feature your plan does not include: API access for webhooks, the account hierarchy feature for child accounts, the B2C use case for donor widgets and receipts, a custom domain, or more user seats.

**Fix**: see which feature each flow needs in [Plans and prerequisites](https://www.charitips.com/docs/overview/plans.md), then contact us.

### A call answers `429 Rate limit exceeded`

**Cause**: too many calls to an endpoint that has a limit, such as the bulk download links.

**Fix**: wait the number of seconds in the `Retry-After` header, then send the call once more. Never retry in a loop.

### A call answers `500` with another message

**Cause**: something failed on our side.

**Fix**: retry once with the same `uniqueExternalId`: a duplicate then answers `409`, not a second donation. If it fails again, contact us with the time of the call.