Virtuous CRM Error Messages

This document catalogs the user-facing error messages that the iPaaS.com Virtuous CRM integration can produce, grouped by mapping collection flow. Use it to identify the cause of an error you see in the iPaaS.com error log and to determine the appropriate next step.

Internal SDK and framework errors are not included — only messages that a subscriber or support agent will actually see in iPaaS.com surface output. For broader integration-level constraints, see the Virtuous CRM Integration Known Limitations article.

Supported Flows

Add/Update Virtuous CRM Gift TO iPaaS.com (Gift → Transaction transfer)
Connection establishment (subscription startup and credential validation)

Error Collection

Connection Establishment

Credential Failure

Unable to obtain access token from Virtuous CRM. Please verify your Username and Password in the subscription presets.

Description: The integration could not exchange the User Name and Password stored on the iPaaS.com Subscription Settings page for an access token. This typically means one of the following has happened to the Virtuous CRM user account behind the credentials: the password has been rotated or expired, the account has been locked, the account has been deleted, or the account's permissions / scopes no longer allow API access. The error fires at subscription startup and on subsequent reconnect attempts.
Resolution: Open the affected Virtuous CRM user account in the Virtuous CRM admin UI and confirm it is active and has the required permissions. Update or unlock the password as needed. Then return to the iPaaS.com Virtuous CRM Subscription Settings page and re-enter the updated User Name, Password, and Grant Type values. The integration will retry the access-token exchange automatically. If the credentials look correct and the error continues, contact iPaaS.com Product Support for assistance.

Add/Update Virtuous CRM Gift TO iPaaS.com

Duplicate Link Failure (Fallback Collision Detection)

Unable to dynamically link to existing Virtuous CRM gift using Id. This may result in duplicate transaction records.

Description: When the integration receives a webhook for a Virtuous gift id that has no existing external-ID record in iPaaS.com, it falls back to matching against any iPaaS.com Transaction whose TransactionNumber equals the Virtuous gift id. If a matching Transaction is found, the integration attempts to record an external-ID entry linking the two so the Transaction will be updated rather than duplicated. This error fires when that external-ID write fails (the platform returned an unexpected external ID, or the link could not be persisted). When this happens the transfer proceeds as an Add, which can produce a duplicate iPaaS.com Transaction for the same Virtuous gift.
Resolution: Review the iPaaS.com Transactions list for duplicate entries sharing the same TransactionNumber. If a duplicate exists, delete the unwanted Transaction in iPaaS.com to clean up. Then check whether the TransactionNumber on the iPaaS.com side actually matches the Virtuous gift id — if the TransactionNumber mapping has been modified, restore it to the default Id → TransactionNumber mapping (see the Known Limitations article). If the issue persists after a clean retry, contact iPaaS.com Product Support for assistance.

Generic Virtuous CRM API Error

Error calling Virtuous CRM CallWrapper.{action}: {response body} (Http Code: {status})

Description: This is a generic envelope the integration wraps around any unsuccessful response from the Virtuous CRM API. The {action} placeholder identifies the operation that failed (for example, Gift.GET (id: 45)), {response body} carries the raw error body that Virtuous CRM returned, and {status} is the HTTP status code. Common causes include: the gift id does not exist in Virtuous CRM (404), the OAuth token has been revoked or has insufficient scope (401 / 403), or the Virtuous CRM API is temporarily unavailable (5xx). The integration cannot modify this message text — it comes from Virtuous CRM.
Resolution: Read the parsed {response body} and {status} to identify the cause:
- 404 Not Found: the Virtuous gift may have been deleted in Virtuous CRM after the webhook was queued, or the wrong gift id was entered on the Manual Sync page. No action is required for deleted gifts; verify the id and retry for manual syncs.
- 401 Unauthorized / 403 Forbidden: the OAuth tokens are no longer valid or the user account lost permission. Re-enter the credentials on the iPaaS.com Subscription Settings page (same workflow as the Credential Failure error above).
- 5xx Server Error: transient Virtuous CRM unavailability. The transfer will be retried automatically by iPaaS.com; no action is required unless the error continues for an extended period.
- For any other status or a body the resolution above does not cover, contact iPaaS.com Product Support for assistance.

Rate-Limit Exceeded

(automatic — no user-visible error message in this case)

Description: Not strictly an error message, but documented here for completeness. When Virtuous CRM responds that the per-hour rate limit (1,500 requests/hour per API token) has been reached, the integration does not throw a user-facing error. Instead it raises an internal QuotaException with a one-minute reset window and iPaaS.com automatically reschedules the affected transfers. No subscriber action is required.
Resolution: None — the integration handles rescheduling automatically. If a large burst of work takes longer than expected to drain, see the Known Limitations article for context on the hourly cap and how the queue catches up.