Overview
This article catalogs the errors subscribers can meet with the Chargebee integration, grouped by flow. Each error carries a stable code you can search for on this page, followed by the message, what causes it, and how to resolve it. Errors appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs.
iPaaS.com categorizes errors by families. You can learn more about that categorization at Understanding iPaaS.com API Error Codes.
Some resolutions refer to your Managed Integration Service Provider (MiSP): the partner who set up and manages your iPaaS.com integration, including its mappings, its connection settings and credentials, and any reconciliation between Chargebee and iPaaS.com.
Each code below comes from the Chargebee integration, has three segments, such as CHGB-VALD-1001, and appears as {code} - {message}. Errors iPaaS.com itself records, with two-segment codes such as NFND-1029, are explained in Understanding iPaaS.com API Error Codes. In the messages below, words in braces are filled in when the error happens, for example {email}.
When a transfer fails, iPaaS.com retries it automatically while its error is active, so fix the cause first; the next retry, or a re-send of the record, then succeeds. Dismiss an active error only when the record should not be retried: dismissing it stops the retry. An error that already shows Retry Pending has started reprocessing, and dismissing it then does not stop that reprocessing.
Situations the integration handles without an error are described in the Chargebee Integration Known Limitations and the Chargebee mapping documentation. Among them: a customer with no email is skipped by the default Customer TO iPaaS.com filter; when Chargebee's rate limit is reached, the integration asks iPaaS.com to hold the transfer until the limit resets (the wait Chargebee states, or 60 seconds) and retry it (subscribers or their MiSP should validate this in a staging environment before running large loads); and when Initial Poll Days or Poll Page Size is out of range or a fraction, the integration uses the nearest allowed value and writes a warning naming the setting and the value it used in the transfer's activity log under Dashboard / Integration Monitoring.
Supported Flows
Connection and settings
Customer TO iPaaS.com
Item Price TO iPaaS.com
Invoice and Credit Note TO iPaaS.com
Customer FROM iPaaS.com
Webhook scopes
Any flow
Error Collection
Connection and settings
The integration checks the connection before every transfer. When the check fails, the transfer's error reads only "Unable to connect to subscription with id {subscription id}", and the integration's coded reason is in Logs at the error's time. The codes in this section are found there.
Required setting missing or not a site name
CHGB-AUTH-1001 - The "Chargebee Site" setting does not hold a Chargebee site name (it looks like an API key: the key belongs in the "API Key" setting). Enter the site name from your Chargebee address (for "acme-test.chargebee.com" enter "acme-test").
CHGB-AUTH-1001 - The "Chargebee Site" setting is empty. Enter the site name from your Chargebee address (for "acme-test.chargebee.com" enter "acme-test").
CHGB-AUTH-1001 - The "API Key" setting is empty. Create a full-access API key in Chargebee (Settings > Configure Chargebee > API Keys and Webhooks) and enter it.
Description: Chargebee Site holds something that is not a Chargebee site name, or a required setting is empty. The part in brackets appears only when the value looks like an API key, which usually means the key was pasted into Chargebee Site; the value itself is never repeated in the message. Chargebee Site accepts the bare site name (acme-test) or the full address (acme-test.chargebee.com). iPaaS.com normally refuses to save an empty Chargebee Site or API Key, so the two "is empty" messages are rare.
Resolution: Enter the site name from your Chargebee address in Chargebee Site, and a full-access API key from Chargebee (Settings > Configure Chargebee > API Keys and Events) in API Key, then save the subscription. The waiting transfers succeed on their next retry.
Chargebee refused the API key
CHGB-AUTH-1002 - Chargebee refused {action}: {Chargebee message}; code {Chargebee error code}; field {field} (HTTP 401). Create a full-access API key on this site (Settings > Configure Chargebee > API Keys and Webhooks) and save it in the API Key setting.
Description: Chargebee did not accept the API key: it is wrong, deleted, or belongs to another Chargebee site. Chargebee's own reason follows the action, for example "Sorry, authentication failed. Invalid api key; code api_authentication_failed". The code and field parts appear only when Chargebee sends them. A key that Chargebee accepts but does not allow to do something is CHGB-AUTZ-1001.
Resolution: In Chargebee, create a full-access API key on the site named in Chargebee Site (Settings > Configure Chargebee > API Keys and Events), save it in API Key, and save the subscription.
Chargebee Site changed after records were linked
CHGB-BIZL-1008 - This subscription was first connected to the Chargebee site "{remembered site}", but the Chargebee Site setting now names "{new site}". Chargebee numbers every site's records from 1, so the new site's records could overwrite the ones it sent TO iPaaS.com. Change Chargebee Site back to "{remembered site}", or add a new subscription for "{new site}".
Description: Chargebee Site was changed to a different, existing Chargebee site after the subscription had connected to another one. The subscription remembers the Chargebee site it first exchanged data with. Nothing is read or written while this error stands. A mistyped site never connects (it gives CHGB-NFND-1001 with site_not_found), so it is never remembered.
Resolution: Change Chargebee Site back to the site the message names; the waiting transfers then succeed on their next retry. To connect the other Chargebee site, add a new iPaaS.com subscription for it, with its own API key.
Site not on Product Catalog 2.0
CHGB-BIZL-1009 - This Chargebee site does not answer item price requests. The integration needs Product Catalog 2.0 (items and item prices); this site is still on Product Catalog 1.0 (Chargebee: {Chargebee message}). Connect a site that uses Product Catalog 2.0, or ask Chargebee support about moving this site to it.
Description: The connection check before every transfer reads one item price. When Chargebee refuses that read with its error code configuration_incompatible, the integration treats the site as one that does not use items and item prices (Product Catalog 2.0) and reports this code. Every transfer then fails until the subscription points at a site that answers item price requests.
Resolution: Connect a Chargebee site that uses Product Catalog 2.0, or ask Chargebee support about moving this site to it. A retry can't succeed on a Product Catalog 1.0 site, so once the setting points at the right site, dismiss the active errors to stop their retries. An error that already shows Retry Pending is reprocessed anyway; if that fails again, dismiss the error it raises. Subscribers or their MiSP should confirm the site's catalog version in a staging environment before relying on it in production.
Chargebee could not be reached
CHGB-EXTN-1002 - Could not reach Chargebee for {action}: {network message}. Check that Chargebee Site holds only the site name (e.g. acme-test); if it does, Chargebee or the network is unavailable and the transfer retries by itself.
Description: No answer came back from Chargebee at all, for example "Name or service not known" for an address that does not exist, or a network or secure-connection failure. A Chargebee Site value with extra text in it is one cause.
Resolution: Check that Chargebee Site holds only the site name or the site's address. If it does, nothing is needed: a later retry succeeds once Chargebee answers again.
Customer TO iPaaS.com
These errors occur on Add/Update Chargebee Customer TO iPaaS.com and its billing address child. Before a Chargebee customer is mapped, the integration links it to the one iPaaS.com customer with the same email, when there is exactly one. CHGB-BIZL-1002 and CHGB-BIZL-1006 can also appear on an invoice or credit note whose customer is sent first.
Several iPaaS.com customers have the email
CHGB-BIZL-1002 - {n} iPaaS.com customers have the email {email} (ids {iPaaS.com customer ids}), so Chargebee customer {Chargebee customer id} can't be linked to one. Merge them in iPaaS.com, then re-sync.
Description: Two or more iPaaS.com customers have the Chargebee customer's email, so the integration won't guess which one to link. Emails that differ only in letter case count as the same email here.
Resolution: Merge the iPaaS.com customers the message lists, or change their emails so only one remains, then re-send the Chargebee customer.
Email already linked to another Chargebee customer
CHGB-BIZL-1006 - iPaaS.com customer {iPaaS.com customer id} has the email {email} and is already linked to Chargebee customer {other Chargebee customer id}, so Chargebee customer {Chargebee customer id} was not sent (iPaaS.com allows one customer per email). Give one of the two Chargebee customers a different email, or merge them in Chargebee.
Description: Two Chargebee customers share one email, and the iPaaS.com customer with that email is already linked to the other one. iPaaS.com refuses a second customer with an identical email, so this one is not sent. Nothing is written.
Resolution: Give one of the two Chargebee customers a different email, or merge them in Chargebee, then re-send the customer.
Item Price TO iPaaS.com
These errors occur on Add/Update Chargebee Item Price TO iPaaS.com. Before an item price is mapped, the integration links it to the one iPaaS.com product whose SKU is the item price id, when there is exactly one. CHGB-BIZL-1007 can also appear on an invoice or credit note whose item price is sent first.
Duplicate or taken product SKU
CHGB-BIZL-1007 - {n} iPaaS.com products have the SKU {SKU} (ids {iPaaS.com product ids}), so Chargebee item price {item price id} can't be linked to one. Remove the duplicates in iPaaS.com, then re-sync.
CHGB-BIZL-1007 - iPaaS.com product {iPaaS.com product id} has the SKU {SKU} but is already linked to Chargebee item price {other item price id}, so nothing was sent. Give one of them a different SKU in iPaaS.com, or remove the other link, then re-sync.
Description: Two or more iPaaS.com products have the item price id as their SKU, or the one product with that SKU is already linked to a different Chargebee item price. Nothing is sent.
Resolution: Remove the duplicate products in iPaaS.com, or give one of them a different SKU, or remove the other link, then re-send the item price.
Invoice and Credit Note TO iPaaS.com
These errors occur on Add/Update Chargebee Invoice TO iPaaS.com, Add/Update Chargebee Credit Note TO iPaaS.com and their child collections. Nothing of the invoice or credit note is saved while one of them stands.
A record the document needs could not be sent first
CHGB-NFND-1002 - The {customer / product / transaction} {Chargebee id} this record needs could not be sent TO iPaaS.com first; the transfer will retry. If it keeps failing, open that record's own error in iPaaS.com and fix it first.
Description: An invoice's customer or one of its item prices, or a credit note's invoice, is sent to iPaaS.com first, and it failed. When that record's own error is known, the invoice or credit note shows that error instead (for example VALD-1039, CHGB-BIZL-1002, CHGB-BIZL-1006 or CHGB-BIZL-1007); this code appears only when it isn't.
Resolution: Open the error of the customer, item price or invoice the message names, fix it, and the invoice or credit note follows on its next retry or a re-send.
Customer FROM iPaaS.com
These errors occur on Add/Update Chargebee Customer FROM iPaaS.com and its billing address child. The integration checks the customer before anything is written to Chargebee.
Customer data can't be used in Chargebee
CHGB-VALD-1001 - The customer has no email, name or company; Chargebee needs at least one to identify the billing account. Fill one in on the iPaaS.com customer (or map it), then re-send it.
CHGB-VALD-1001 - The email "{email}" is not a valid address. Correct it on the iPaaS.com customer, then re-send it.
CHGB-VALD-1001 - AutoCollection must be on or off, not "{value}". Correct the AutoCollection mapping (or its translation), then re-send the customer.
CHGB-VALD-1001 - Taxability must be taxable or exempt, not "{value}". Correct the Taxability mapping (or its translation), then re-send the customer.
CHGB-VALD-1001 - The customer id "{id}" can't be used in Chargebee: at most 50 letters, digits, and _ - . @. Map an id that fits, or leave the Id mapping empty so Chargebee makes one, then re-send the customer.
CHGB-VALD-1001 - The billing country "{country}" must be a two-letter ISO code (e.g. US, GB); map it with a translation.
CHGB-VALD-1001 - The country "{country}" has no row in the country translation, so the billing address was not sent (it would have cleared Chargebee's country). Add the two-letter ISO code for it to the translation, then re-send.
Description: A value the customer needs is missing or malformed, a mapped value is not one Chargebee accepts, or Chargebee Country FROM iPaaS.com has no row for the customer's country. Nothing is written to Chargebee.
Resolution: Do what the message says: fill in or correct the value on the iPaaS.com customer; map AutoCollection to on or off and Taxability to taxable or exempt (with a translation if needed); map a customer Id that fits, or leave the Id mapping empty so Chargebee makes one; or add the missing country to Chargebee Country FROM iPaaS.com with its two-letter ISO code and save the translation collection. Then re-send the customer.
Several Chargebee customers have the email
CHGB-BIZL-1001 - {n} Chargebee customers have the email {email} ({Chargebee customer ids}). Merge or change them in Chargebee, then re-sync.
Description: Chargebee allows several customers with one email. When a new iPaaS.com customer's email matches two or more Chargebee customers, the integration won't guess which one is meant.
Resolution: Merge the Chargebee customers the message lists, or change their emails so only one remains, then re-send the iPaaS.com customer.
Edited in Chargebee since the last sync
CHGB-BIZL-1003 - Chargebee customer {Chargebee customer id} was edited in Chargebee after iPaaS.com last wrote it ({fields}), and this update would overwrite that edit with a different value, so it was not sent. To keep Chargebee's version, set those fields on the iPaaS.com customer to Chargebee's values and re-send it. To keep iPaaS.com's version, make the same change in Chargebee, then re-send the customer.
Description: A field this update would change (name, email, phone, company, a custom field or a billing address field) was edited in Chargebee since iPaaS.com last wrote it, and the update carries a different value. The message names the fields. An address edit in Chargebee that leaves fields blank counts as an edit of each field it cleared.
Resolution: Decide which version wins. To keep Chargebee's, set the named fields on the iPaaS.com customer to Chargebee's values, then re-send it. To keep iPaaS.com's, make the same change in Chargebee, then re-send the customer. Dismissing the error does not settle it: the next update that carries that field is refused again.
Webhook scopes
These errors are raised when a Chargebee webhook scope is set Active on the subscription, not by a record's transfer. iPaaS.com retries the failed registration automatically while its error is active.
Webhook endpoint limit reached
CHGB-EXTN-1004 - Chargebee allows 5 webhook endpoints per site and this site has {n}. Remove one you no longer use in Chargebee (Settings > Configure Chargebee > API Keys and Webhooks, Webhooks tab), then set this webhook scope Active again.
Description: When a scope is set Active, the integration registers one webhook endpoint on the Chargebee site, and it checks first that the site has fewer than five, the most Chargebee allows ("You can create up to five webhook endpoints per site", Chargebee webhook endpoints reference). It comes from the same registration step as CHGB-EXTN-1005, which is written to the company's Logs, so look for it in Logs first. If the scope's events never arrive, also count the site's webhook endpoints in Chargebee's webhook settings. Subscribers or their MiSP should validate this in a staging environment.
Resolution: In Chargebee, delete an endpoint you no longer use (Settings > Configure Chargebee > API Keys and Events, then the Webhooks tab). Then set the webhook scope Active again. iPaaS.com also retries the registration while the error is active, but each retry fails until the site has fewer than five endpoints; if you leave the scope inactive, dismiss its active error in Dashboard / Integration Monitoring / Error Logs.
Webhook endpoint registered moments ago
CHGB-EXTN-1005 - Chargebee is still setting up this subscription's webhook endpoint, so the webhook could not be turned on yet. Wait a few minutes, then set this webhook scope Active again.
Description: Two scopes were set Active close together. Chargebee had created the endpoint for the first but did not list it yet, and refused a second endpoint with the same name. A new endpoint can take more than ten minutes to appear in Chargebee's endpoint list. The message is written to the company's Logs about ten seconds after the scope is set Active; look for it there. In Chargebee, the subscription's endpoint exists but is not yet listed in the webhook settings.
Resolution: iPaaS.com retries the registration automatically while the error is active, so the scope does not have to be set Active again. After about half an hour, check in Chargebee that the subscription's endpoint carries the scope's event; if it does not, set the scope Active again. If you set the scope inactive instead, dismiss its active error in Dashboard / Integration Monitoring / Error Logs. An error that already shows Retry Pending is reprocessed anyway, so afterwards check the endpoint's events in Chargebee and remove the scope's event there if it was added.
Any flow
These errors can occur on any collection.
API key not allowed to do this
CHGB-AUTZ-1001 - Chargebee refused {action}: {Chargebee message}; code {Chargebee error code}; field {field} (HTTP 403). The API key is not allowed to do this: save a full-access key in the API Key setting (a read-only or restricted key can't write).
Description: Chargebee accepted the API key but did not allow the request; Chargebee returns this when "the API key does not have sufficient privileges to perform the particular operation" (Chargebee's error handling reference). A read-only or restricted key is refused wherever it lacks permission: on the connection check when it cannot read item prices, and on writes such as a customer FROM iPaaS.com or the webhook endpoint registered when a scope is set Active. Subscribers or their MiSP should validate a restricted key in a staging environment before relying on it.
Resolution: Create a full-access API key on the site named in Chargebee Site (Settings > Configure Chargebee > API Keys and Events), save it in API Key, and save the subscription.
Chargebee refused a request
CHGB-EXTN-1001 - Chargebee refused {action}: {Chargebee message}; code {Chargebee error code}; field {field} (HTTP {status}). Correct the value Chargebee names (check the mapping that fills it), then let the transfer retry.
Description: Chargebee rejected the data sent or the request, and the message quotes Chargebee's reason, its error code and the field. For example, "first_name : The size should not be more than 150; code param_wrong_value; field first_name (HTTP 400)" for a first name longer than Chargebee allows.
Resolution: Read Chargebee's reason and the field it names, then correct the value in the source record or in the mapping that fills that field. The next retry, or a re-send, then succeeds.
Chargebee server error
CHGB-EXTN-1003 - Chargebee refused {action}: {Chargebee message}; code {Chargebee error code}; field {field} (HTTP {status}). Chargebee had a problem; the transfer retries by itself.
Description: Chargebee answered with a server error (HTTP 500 or above): the request was valid but failed on Chargebee's side.
Resolution: None needed: a later retry succeeds once Chargebee recovers. If it persists, check Chargebee's status page, then re-send the record.
Chargebee record or site not found
CHGB-NFND-1001 - Chargebee refused {action}: {Chargebee message}; code site_not_found (HTTP 404). No Chargebee site has this name: correct the Chargebee Site setting and keep the existing links.
CHGB-NFND-1001 - Chargebee refused {action}: {Chargebee message}; code {Chargebee error code}; field {field} (HTTP 404). The record was probably deleted in Chargebee: dismiss the error, or remove this record's link in iPaaS.com so it can be sent again.
CHGB-NFND-1001 - Chargebee customer {Chargebee customer id} no longer exists, so it could not be updated. Remove its link in iPaaS.com to create it again.
Description: With site_not_found, Chargebee Site names no Chargebee site; this shows in Logs behind "Unable to connect to subscription with id {subscription id}", and the records are not at fault. Otherwise, the linked Chargebee record was deleted in Chargebee or the linked id is wrong; the third message is a Customer FROM iPaaS.com update of a customer deleted in Chargebee.
Resolution: For site_not_found, correct Chargebee Site and keep every link. Otherwise, remove the record's link in iPaaS.com so it is created again, or relink it to the right Chargebee record, then re-send it; if the record should stay deleted, dismiss the active error so it is not retried. An error that already shows Retry Pending is reprocessed anyway; if that fails again, dismiss the error it raises.
Record id missing
CHGB-VALD-1002 - An update reached Chargebee without a customer id. Remove this customer's Chargebee link in iPaaS.com and re-send it, so it is matched or created again.
CHGB-VALD-1002 - An invoice or credit note transfer arrived without an id. Dismiss this error and re-send the document; if it happens again, contact iPaaS.com Support with this message.
Description: A Customer FROM iPaaS.com update reached Chargebee with an empty customer id, or an invoice or credit note transfer arrived with an empty id.
Resolution: For a customer, remove the customer's Chargebee link in iPaaS.com and re-send it, so it is matched or created again. For an invoice or credit note, re-send the document by its Chargebee id; the failed transfer's own retry cannot succeed, so dismiss its active error to stop it. If it happens again, contact your MiSP, or iPaaS.com Support at support@ipaas.com, with the message and the transfer's tracking id.
Unsupported data type
CHGB-BIZL-1004 - Chargebee does not support data type {type number} ({type name}) in this integration. Remove or turn off the mapping collection that sends it.
Description: A mapping collection sends a type of data this integration does not handle. No retry can succeed.
Resolution: Remove or turn off that mapping collection, then dismiss the active errors to stop their retries. An error that already shows Retry Pending is reprocessed anyway; if that fails again, dismiss the error it raises.
Operation not supported
CHGB-BIZL-1005 - Invoices and credit notes are created in Chargebee, never FROM iPaaS.com (Chargebee owns billing). Remove or turn off the FROM iPaaS.com mapping collection for invoices and credit notes.
CHGB-BIZL-1005 - Invoices and credit notes are changed in Chargebee, never FROM iPaaS.com (Chargebee owns billing). Remove or turn off the FROM iPaaS.com mapping collection for invoices and credit notes.
CHGB-BIZL-1005 - Invoices and credit notes are not deleted FROM iPaaS.com. Turn off deletes for this mapping collection; void or delete the document in Chargebee instead.
CHGB-BIZL-1005 - Invoices and credit notes are not written FROM iPaaS.com. Remove or turn off this FROM iPaaS.com mapping collection.
CHGB-BIZL-1005 - This record moves with its invoice or credit note; transfer the document.
CHGB-BIZL-1005 - This record moves with its invoice or credit note; poll the documents.
CHGB-BIZL-1005 - Deleting Chargebee customers is not supported: a customer's invoices and subscriptions depend on it. Turn off deletes for the Customer FROM iPaaS.com mapping collection.
CHGB-BIZL-1005 - A billing address moves with its customer; transfer the customer.
CHGB-BIZL-1005 - A billing address moves with its customer; poll customers.
CHGB-BIZL-1005 - Item prices are set up in Chargebee by the billing team; the integration never creates or changes them FROM iPaaS.com. Remove or turn off the Product FROM iPaaS.com mapping collection.
CHGB-BIZL-1005 - Deleting Chargebee item prices is not supported. Turn off deletes for this mapping collection; archive the item price in Chargebee instead.
Description: A collection asks for something the integration does not do: a product (item price), invoice or credit note written FROM iPaaS.com, a delete, or a child record (an invoice or credit note line, payment, tax, discount or address, or a billing address) transferred on its own. Products, invoices and credit notes travel only TO iPaaS.com, and child records travel with their parent. No retry can succeed.
Resolution: Remove or turn off the mapping collection the message names, or turn off its delete trigger (for example customer/deleted on Add/Update Chargebee Customer FROM iPaaS.com). Transfer the parent invoice, credit note or customer instead of the child. Then dismiss the active errors to stop their retries. An error that already shows Retry Pending is reprocessed anyway; if that fails again, dismiss the error it raises.
iPaaS.com lookup failed
CHGB-INTL-1002 - iPaaS.com could not complete a lookup the transfer needs (HTTP {status}). The transfer will retry by itself; if it keeps failing, contact iPaaS.com Support with this message.
CHGB-INTL-1002 - {mapping function} could not look up the iPaaS.com record linked to Chargebee {Chargebee id}, so this transfer was stopped rather than sent without it. It is retried automatically.
Description: A lookup the integration makes in iPaaS.com failed: a link lookup, a customer or product search, or the lookup a mapping function such as ChargebeeCustomerIPaaSId or ChargebeeInvoiceIPaaSId makes for a linked customer or invoice. The transfer stops rather than save an invoice or credit note without its customer or parent invoice.
Resolution: None at first: a later retry succeeds once iPaaS.com answers again. If it keeps failing, contact your MiSP, or iPaaS.com Support at support@ipaas.com, with the message and the transfer's tracking id.
Internal guard
CHGB-INTL-1001 - {internal detail} This is an error inside the integration: dismiss it and contact iPaaS.com Support with this message.
Description: An internal safeguard: a record or value of an unexpected kind reached the integration. The internal detail names the step that stopped. Nothing on the subscription causes it, and no retry can succeed.
Resolution: Contact your MiSP, or iPaaS.com Support at support@ipaas.com, with the full message and the transfer's tracking id. No retry can succeed, so once you have the message, dismiss the active error to stop its retries.