API reference

Troubleshooting

Build with AI

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 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.

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.

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.

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.

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

Cause: the campaign has no charities selection.

Fix: create a selection 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.

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, 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.

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, 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 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 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.

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, 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: 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 and Get a charity.

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.

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.

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.

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, 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.