Blackbaud Raiser's Edge NXT Error Messages
This document catalogs all user-facing error messages within the Blackbaud Raiser's Edge NXT integration, grouped by mapping collection flow. It helps end users and support staff identify, understand, and resolve errors encountered during data synchronization between iPaaS.com and Blackbaud Raiser's Edge NXT.
Supported Flows
Authentication and Connection
Missing Client ID
Unable to complete OAuth process in ProcessAuthorization. ClientId is not specified in the Integration Settings.
Description: The OAuth authorization flow was initiated but the Application ClientId subscription setting is empty or missing. This occurs when the subscriber clicks the Authorize action on the Subscription Settings page before entering the required credentials.
Resolution: Navigate to the iPaaS.com Subscription Settings page and enter the Application ClientId obtained from the Blackbaud developer portal. Click Apply, then re-run the OAuth authorization.
Missing Client Secret
Unable to complete OAuth process in ProcessAuthorization. ClientSecret is not specified in the Integration Settings.
Description: The OAuth authorization flow was initiated but the Application ClientSecret subscription setting is empty or missing.
Resolution: Navigate to the iPaaS.com Subscription Settings page and enter the Application ClientSecret obtained from the Blackbaud developer portal. Click Apply, then re-run the OAuth authorization.
Token Exchange Failure
Unable to complete OAuth process in ProcessAuthorization. Failed to convert temporary code into a permanent token
Description: The integration received an authorization code from Blackbaud but failed to exchange it for an access token and refresh token. This typically occurs when the Application ClientId or Application ClientSecret is incorrect, has been regenerated since the last successful authorization, or when the redirect URI configuration does not match between Blackbaud's application registration and iPaaS.com.
Resolution: Verify the Application ClientId and Application ClientSecret match the values in the Blackbaud developer portal under My applications. If the credentials were recently rotated, update them in Subscription Settings and click Apply. Re-run the OAuth authorization.
Token Refresh Failure
Unable to refresh access token.
Description: The integration attempted to automatically refresh the expired access token using the stored refresh token, but the refresh failed. This occurs when the refresh token has expired, the application secret has been regenerated in the Blackbaud developer portal, or the subscriber has revoked access in their Blackbaud account.
Resolution: Re-run the OAuth authorization from the iPaaS.com Subscription Settings page by clicking the Authorize action (lock icon). If the application secret was recently regenerated, update the Application ClientSecret setting first.
Constituent — To iPaaS.com
Invalid Constituent Key
Invalid key value at {Location}. MappingCollectionType = CUSTOMER, ExpectedDataType = Integer, PKValue = {Id}
Description: The Constituent ID supplied for transfer could not be parsed as the expected numeric value. This typically occurs when a non-numeric or empty value was entered for transfer.
Resolution: This error indicates a malformed external ID was passed for transfer that could not be processed. Verify a valid Constituent ID has been provided for transfer to iPaaS.com — for Manual Sync, enter the numeric Raiser's Edge NXT system record ID (e.g.,
280). If the issue persists, contact iPaaS.com Support at support@ipaas.com.
Rate Limit Exceeded
Rate Limit - Raiser's Edge NXT: Received 429 from {Action}. Rescheduling retry in {RetryAfterSec}s.
Description: The Blackbaud SKY API returned a 429 Too Many Requests response, indicating the integration has exceeded the API rate limit. iPaaS.com automatically reschedules the request after the Retry-After period specified by Blackbaud. No data is lost.
Resolution: No action required — the transfer is automatically rescheduled. If rate limits are triggered frequently, consider reducing the API Throttle Limit (to iPaaS.com) or increasing the API Throttle Seconds (to iPaaS.com) on the Subscription Settings page. For sustained high-volume usage, upgrade to a higher Blackbaud SKY API tier in the Blackbaud developer portal.
Constituent — From iPaaS.com
Invalid Constituent Key
Invalid key value at {Location}. MappingCollectionType = CUSTOMER, ExpectedDataType = Integer, PKValue = {Id}
Description: The iPaaS.com Customer ID supplied for transfer could not be parsed as the expected numeric value. This typically occurs when a non-numeric or empty value was entered for transfer.
Resolution: This error indicates a malformed external ID was passed for transfer that could not be processed. Verify a valid iPaaS.com Customer ID has been provided for transfer to Raiser's Edge NXT — for Manual Sync, enter the numeric iPaaS.com Customer record ID (e.g.,
12094). If the issue persists, contact iPaaS.com Support at support@ipaas.com.
Batch Execution Error
Received an exception during batch run of {Action}. {FirstExceptionMessage}
Description: An error occurred while processing a batch of API calls to Blackbaud. The error message includes the specific action that failed and the details of the first exception encountered. This can occur during batch constituent creation or update operations.
Resolution: Review the exception detail in the error message. If the exception references a specific Blackbaud validation error (e.g., a missing table entry or invalid field value), correct the source data in iPaaS.com and retry the transfer. If the error is not actionable, contact iPaaS.com Support at support@ipaas.com.
Rate Limit Exceeded
Rate Limit - Raiser's Edge NXT: Received 429 from {Action}. Rescheduling retry in {RetryAfterSec}s.
Description: The Blackbaud SKY API returned a 429 Too Many Requests response during an outbound transfer. iPaaS.com automatically reschedules the request.
Resolution: No action required — the transfer is automatically rescheduled. If rate limits are triggered frequently, reduce the API Throttle Limit or increase the API Throttle Seconds on the Subscription Settings page.
Constituent Address — To iPaaS.com
Invalid Address Key
Invalid key value at {Location}. MappingCollectionType = CUSTOMER_ADDRESS, ExpectedDataType = Integer, PKValue = {Id}
Description: The Address ID supplied for transfer could not be parsed as the expected numeric value. This typically occurs when a non-numeric or empty value was entered for transfer.
Resolution: This error indicates a malformed external ID was passed for transfer that could not be processed. Verify a valid Address ID has been provided for transfer to iPaaS.com — for Manual Sync standalone address transfers, enter the numeric Raiser's Edge NXT Address ID (e.g.,
67890). If the issue persists, contact iPaaS.com Support at support@ipaas.com.
General API Errors
These errors can occur across any mapping collection flow and originate from the Blackbaud SKY API. The integration parses and surfaces error details from three response shapes used by the Blackbaud platform.
Validation Error (Field-Level)
Error calling Raiser's Edge NXT.APICall.{Action}: [{error details}] (Http Code: BadRequest)
Description: The Blackbaud SKY API rejected the request because one or more fields failed validation. The error details contain the specific validation failure from Blackbaud, such as a missing required field, an invalid table entry, or a data type mismatch. Common examples include a table entry reference that doesn't exist (e.g., a phone type or address type not configured in Blackbaud), a required field that was not provided, or a value that doesn't match the expected format.
Resolution: Review the error detail text in the message — it contains the specific Blackbaud validation failure. Correct the source data or mapping configuration in iPaaS.com to match the values configured in the Blackbaud environment. If the error references a missing table entry, add the entry in the Blackbaud application before retrying.
Authentication Error
Error calling Raiser's Edge NXT.APICall.{Action}: {"title": "Unauthorized", "status": 401, ...} (Http Code: Unauthorized)
Description: The API call was rejected because the access token is invalid or expired, and automatic token refresh failed. This can occur if the refresh token has also expired or if the application credentials were changed in the Blackbaud developer portal.
Resolution: Re-run the OAuth authorization from the iPaaS.com Subscription Settings page. If the error persists, verify the Application ClientId, Application ClientSecret, and Blackbaud Subscription Key are correct.
Insufficient Scope
Error calling Raiser's Edge NXT.APICall.{Action}: {"title": "Forbidden", "status": 403, "detail": "This application has insufficient scope to perform the operation."} (Http Code: Forbidden)
Description: The application does not have the required permissions to access the requested API endpoint. This occurs when the Blackbaud application registration does not include the API scopes needed for the operation being performed.
Resolution: In the Blackbaud developer portal, navigate to My applications, select the application, and verify the required API scopes are enabled. The Raiser's Edge NXT integration requires constituent read and write scopes at minimum. After updating scopes, re-run the OAuth authorization to refresh the token with the updated permissions.
Subscription Key Error
Error calling Raiser's Edge NXT.APICall.{Action}: {"statusCode": 401, "message": "Access denied due to invalid subscription key..."} (Http Code: Unauthorized)
Description: The Blackbaud Subscription Key sent with the API request is invalid, expired, or not associated with a valid SKY API subscription.
Resolution: Verify the Blackbaud Subscription Key on the iPaaS.com Subscription Settings page matches the Primary or Secondary access key from the Blackbaud developer portal under My subscriptions. If the key was recently regenerated, update it in iPaaS.com and click Apply.
Resource Not Found
Error calling Raiser's Edge NXT.APICall.{Action}: {response content} (Http Code: NotFound)
Description: The requested resource (constituent, address, custom field, or webhook subscription) was not found in the Blackbaud system. This can occur when a record has been deleted in Blackbaud after iPaaS.com received the webhook notification, or when the ID stored in iPaaS.com no longer matches a valid Blackbaud record.
Resolution: Verify the record exists in Blackbaud Raiser's Edge NXT. If it has been deleted, clear the corresponding mapping in iPaaS.com to allow re-creation on the next sync. If the error persists, contact iPaaS.com Support at support@ipaas.com.
Server Error
Error calling Raiser's Edge NXT.APICall.{Action}: {response content} (Http Code: InternalServerError)
Description: The Blackbaud SKY API returned an internal server error. This is a transient issue on the Blackbaud side and is not caused by the data being sent.
Resolution: Retry the transfer. If the error persists across multiple retries, check the Blackbaud Status Page for any ongoing service issues. If the issue continues, contact iPaaS.com Support at support@ipaas.com.
Request Error (ErrorException)
Received ErrorException from {Action}. See Tech log for more details
Description: A low-level request error occurred while communicating with the Blackbaud SKY API. This may be caused by network timeouts, DNS resolution failures, or SSL certificate issues.
Resolution: Run a manual transfer using the Debug option to examine where the transfer failure is occurring. If the error indicates a network or connectivity issue, verify the API Url subscription setting is correct (default:
api.sky.blackbaud.com). For persistent connectivity issues, contact iPaaS.com Support at support@ipaas.com.