Skip to main content

Blackbaud Raiser's Edge NXT Error Messages

Catalog of user-facing error messages in the iPaaS.com Blackbaud Raiser's Edge NXT integration, grouped by mapping flow, to help you identify and resolve sync errors.

See what the Blackbaud Raiser's Edge NXT integration can do →

Overview

This article catalogs the user-facing error messages within the Blackbaud Raiser's Edge NXT integration, grouped by mapping flow. Each error carries a stable code you can search for on this page, followed by the message, the condition that 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.

Supported Flows

  • Authentication and Connection

  • Constituent and Constituent Address (To and From iPaaS.com)

  • Transaction → Gift (From iPaaS.com)

  • General API Errors

Error Collection

Authentication and Connection

A required OAuth setting is missing

RENX-AUTH-1001 - Unable to complete OAuth process in ProcessAuthorization. {ClientId or ClientSecret} is not specified in the Integration Settings.

  • Description: The OAuth authorization flow was initiated but the Application ClientId or Application ClientSecret subscription setting is empty. This occurs when the Authorize action is clicked before the required credentials are entered.

  • Resolution: On the iPaaS.com Subscription Settings page, enter the Application ClientId and Application ClientSecret obtained from the Blackbaud developer portal (My applications). Click Apply, then re-run the OAuth authorization.

Token exchange failed

RENX-AUTH-1002 - 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 and refresh token. This typically occurs when the ClientId or ClientSecret is incorrect or was regenerated since the last authorization, or when the redirect URI does not match between Blackbaud and iPaaS.com.

  • Resolution: Verify the Application ClientId and Application ClientSecret match the values in the Blackbaud developer portal under My applications. If they were recently rotated, update them in Subscription Settings, click Apply, and re-run the OAuth authorization.

Token refresh failed

RENX-AUTH-1003 - Unable to refresh access token.

  • Description: The integration attempted to 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 was regenerated, or access was revoked in Blackbaud.

  • Resolution: Re-run the OAuth authorization from the Subscription Settings page (the Authorize / lock action). If the application secret was recently regenerated, update the Application ClientSecret first.

Constituent and Constituent Address (To and From iPaaS.com)

Invalid record key

RENX-VALD-1001 - Invalid key value at {Location}. MappingCollectionType = {Type}, ExpectedDataType = {expected}, PKValue = {Id}

  • Description: The identifier supplied for a Constituent or Constituent Address transfer could not be parsed as the expected value (for example, a non-numeric or empty value where a numeric record id is required). The message names the mapping collection type and the expected data type.

  • Resolution: Provide a valid record id for the transfer — for Manual Sync, enter the numeric Raiser's Edge NXT or iPaaS.com record id (e.g., a Constituent id like 280, or an iPaaS.com Customer id like 12094). If it persists, your MiSP can review the mapping and the value being sent.

Batch execution error

RENX-EXTN-1003 - Received an exception during batch run of {Action}. {first exception message}

  • Description: An error occurred while processing a batch of API calls to Blackbaud. The message includes the action that failed and the first exception encountered — for example during batch constituent creation or update.

  • Resolution: Review the exception detail in the message. If it 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. If the detail is not actionable, your MiSP can review the batch and the Blackbaud response.

Rate limiting is handled automatically (not an error). When the Blackbaud SKY API returns HTTP 429 (Too Many Requests), iPaaS.com reschedules the request after the Retry-After period Blackbaud specifies — no data is lost and no action is required. If rate limits trigger frequently, reduce the API Throttle Limit or increase the API Throttle Seconds on the Subscription Settings page, or upgrade your Blackbaud SKY API tier.

Transaction → Gift (From iPaaS.com)

These errors occur when a Transaction is transferred from iPaaS.com and its Gift lines are recorded as gifts in Raiser's Edge NXT.

TransactionType is required

RENX-VALD-1002 - TransactionType is required on the ConstituentActivity mapping. Configure a Static-value mapping with one of: "Gift", "Product", or "Membership" so the integration can route lines to the correct Raiser's Edge NXT endpoint.

  • Description: The Transaction (ConstituentActivity) parent has no TransactionType, so the integration cannot route its lines to the correct Raiser's Edge NXT endpoint.

  • Resolution: On the Transaction mapping collection, add a Static-value mapping for TransactionType set to Gift (the currently supported path). This message is produced by the integration and is not subscriber-editable beyond the mapping.

TransactionNumber is required

RENX-VALD-1003 - TransactionNumber is required on the ConstituentActivity mapping. It forms the left half of the parent external_id ({TransactionNumber}|{TransactionType}).

  • Description: The Transaction parent has no TransactionNumber, which is required to build the parent's external identifier.

  • Resolution: Confirm the TransactionNumber field is mapped and resolves to a value before the transfer runs.

CustomerId is required

RENX-VALD-1004 - CustomerId is required on the ConstituentActivity mapping. The integration uses it to look up the iPaaS Customer's Raiser's Edge NXT Constituent external_id at dispatch time.

  • Description: The Transaction parent has no CustomerId, so the integration cannot resolve the Raiser's Edge NXT Constituent the gift belongs to.

  • Resolution: Confirm the CustomerId field is mapped so the integration can resolve the linked Constituent at dispatch time.

Unknown TransactionType

RENX-VALD-1005 - Unknown TransactionType '{TransactionType}' on activity {TransactionNumber}. Expected one of: "Gift", "Product", "Membership".

  • Description: The TransactionType value does not match a routing path the integration recognizes.

  • Resolution: Set the TransactionType Static mapping to Gift (the currently supported path). Product and Membership routing are not yet implemented (lines of those types are skipped).

Customer is not yet linked to a Constituent

RENX-NFND-1001 - Customer {CustomerId} is not yet linked to a Raiser's Edge NXT Constituent on this subscription.

  • Description: The iPaaS.com Customer on the Transaction has no linked Raiser's Edge NXT Constituent yet. The Customer must be transferred (and linked) before its gifts can be recorded.

  • Resolution: Ensure the Customer has transferred FROM iPaaS.com and is linked to a Constituent before the Transaction dispatches; then reprocess. If it persists, your MiSP can review the Customer prerequisite's activity-tracker output.

Gift line reference is required

RENX-VALD-1006 - ConstituentActivityLine.Reference is required for Gift dispatch.

  • Description: A Gift line has no reference value. The reference (typically the iPaaS-side line id) is required so the gift can be traced back to its originating line via the External Reference custom field.

  • Resolution: Map a unique value to the Gift line's Reference before the transfer runs.

Gift constituent id is required

RENX-VALD-1007 - ConstituentActivity.ConstituentId is required for Gift dispatch.

  • Description: The Gift dispatch could not resolve the Raiser's Edge NXT constituent id on the Transaction parent.

  • Resolution: Confirm the Customer is linked to a Constituent (see RENX-NFND-1001) so the parent's constituent id resolves at dispatch time.

Gift amount is required and must be greater than zero

RENX-VALD-1008 - Line reference '{Reference}': Amount is required and must be greater than zero for Gift dispatch.

  • Description: A Gift line was transferred but its amount was empty, zero, or negative. Every gift in Raiser's Edge NXT must have an amount greater than zero. The {Reference} identifies the specific line.

  • Resolution: Verify the source line has an amount greater than zero, and check the field mapped to the Gift line's amount. Lines that can carry a zero or empty amount should be excluded from the Gift mapping collection's filter so they are not sent as gifts.

Gift type is required

RENX-VALD-1009 - Line reference '{Reference}': Type is required for Gift dispatch (e.g. "Cash", "Pledge").

  • Description: A Gift line has no gift type. Raiser's Edge NXT requires a gift type (such as Cash or Pledge) for every gift.

  • Resolution: Map the Gift line's Type to a valid Raiser's Edge NXT gift type before the transfer runs.

Gift was not returned by Blackbaud

RENX-EXTN-1004 - POST /gift/v1/gifts did not return a gift id for reference '{Reference}'.

  • Description: The gift POST to Blackbaud completed but did not return a gift id, so the integration could not record the created gift.

  • Resolution: Retry the transfer. If it persists, your MiSP can review the Blackbaud response for the affected line, and check the Blackbaud Status Page for service issues.

General API Errors

These originate from the Blackbaud SKY API and can occur across any flow.

Blackbaud SKY API error

RENX-EXTN-1002 - Error calling Raiser's Edge NXT.APICall.{Action}: {response detail} (Http Code: {code})

  • Description: The Blackbaud SKY API rejected the request. The logged message includes the response detail and HTTP status code. The most common conditions are listed below.

  • Common causes and resolutions:

    • Validation error (Http Code: BadRequest) — one or more fields failed validation (a missing required field, an invalid or non-existent table entry such as a phone/address type, or a data-type mismatch). Correct the source data or mapping to match the values configured in Blackbaud; if a table entry is missing, add it in Blackbaud before retrying.

    • Authentication (Http Code: Unauthorized, 401) — the access token is invalid or expired and refresh failed. Re-run the OAuth authorization; verify the Application ClientId, Application ClientSecret, and Blackbaud Subscription Key.

    • Insufficient scope (Http Code: Forbidden, 403) — the Blackbaud application lacks the required API scopes. In the Blackbaud developer portal (My applications), enable the needed scopes (constituent read/write at minimum), then re-run the authorization.

    • Subscription key (Http Code: Unauthorized, "invalid subscription key") — verify the Blackbaud Subscription Key matches the Primary/Secondary key under My subscriptions; update it in iPaaS.com and click Apply if it was regenerated.

    • Resource not found (Http Code: NotFound) — the referenced record no longer exists in Blackbaud. Verify it exists; if it was deleted, clear the corresponding mapping in iPaaS.com to allow re-creation on the next sync.

    • Server error (Http Code: InternalServerError) — a transient Blackbaud issue. Retry; if it persists, check the Blackbaud Status Page.

  • Resolution: Read the response detail in the error log and act on the matching cause above. If the condition is not one you can resolve from the source data or mapping, your MiSP can review the mapping and the Blackbaud configuration.

Blackbaud request or transport error

RENX-EXTN-1001 - Received ErrorException from {Action}. See Tech log for more details

  • Description: A low-level request error occurred while communicating with the Blackbaud SKY API — for example a network timeout, DNS failure, or SSL issue. The technical log carries the underlying detail.

  • Resolution: Run a manual transfer with the Debug option to see where the failure occurs. Verify the API Url subscription setting is correct (default: api.sky.blackbaud.com). For persistent connectivity issues, your MiSP can review the connection.

Related Documents

Related Articles
Did this answer your question?