Overview
This article catalogs the error messages the OpenAI integration can produce, grouped by the mapping collection flow each one belongs to. Errors appear under Dashboard / Integration Monitoring / Error Logs.
Two behaviors that are commonly mistaken for errors are deliberately not listed here, because neither produces a failure a subscriber needs to act on:
A rate limit being reached. When OpenAI reports that the request rate has been exceeded, the transfer is rescheduled automatically and resumes once the limit window has passed. Nothing is lost and no action is required.
A notification without routing details. An inbound notification that does not carry the details the integration attached to the original request is recorded and skipped without raising an error. This is how notifications generated outside the integration are ignored. See the OpenAI Known Limitations article.
Supported Flows
Add/Update OpenAI Customer FROM iPaaS.com
Add/Update OpenAI Product FROM iPaaS.com
Update OpenAI Customer TO iPaaS.com
Add/Update OpenAI Product TO iPaaS.com
Add/Update OpenAI Message TO iPaaS.com
All Flows
Add/Update OpenAI Customer FROM iPaaS.com
Missing Id Mapping
Error message: The destination field {{id}} must be present and defined in your FROM iPaaS.com data mappings. Please correct this and try again.
Description: the collection has no mapping writing to the Id destination, so the enrichment request has nothing to identify the Customer by. The transfer stops before anything is sent to OpenAI.
Resolution: add a Field mapping on this collection with CustomerNumber as the source and Id as the destination. Any value may be used as the source provided it uniquely identifies the Customer, because the return leg relies on it to match the enriched result back to the right record.
Invalid Model Instructions
Error message: The user defined Model Instructions could not be parsed as valid JSON. Please correct the issue and try again. Error Details: [details]
Description: the collection has a ModelInstructions mapping whose value is not valid JSON. That mapping is read as a JSON object of additional request options, so malformed content stops the transfer. The Error Details portion carries the specific parsing complaint.
Resolution: correct the ModelInstructions value so it is a well-formed JSON object, or remove the mapping if no additional request options are needed. The parsing complaint in Error Details identifies where the problem is. ModelInstructions is optional — enrichment works without it.
Add/Update OpenAI Product FROM iPaaS.com
Missing Id Mapping
Error message: The destination field {{id}} must be present and defined in your FROM iPaaS.com data mappings. Please correct this and try again.
Description: the collection has no mapping writing to the Id destination, so the enrichment request has nothing to identify the Product by. The transfer stops before anything is sent to OpenAI.
Resolution: add a Field mapping on this collection with Sku as the source and Id as the destination. Any value may be used as the source provided it uniquely identifies the Product, because the return leg relies on it to match the enriched result back to the right record.
Invalid Model Instructions
Error message: The user defined Model Instructions could not be parsed as valid JSON. Please correct the issue and try again. Error Details: [details]
Description: the collection has a ModelInstructions mapping whose value is not valid JSON. That mapping is read as a JSON object of additional request options, so malformed content stops the transfer. The Error Details portion carries the specific parsing complaint.
Resolution: correct the ModelInstructions value so it is a well-formed JSON object, or remove the mapping if no additional request options are needed. ModelInstructions is optional — enrichment works without it.
Update OpenAI Customer TO iPaaS.com
Errors on this flow are returned by OpenAI when the completed enrichment is fetched, or by iPaaS.com when the enriched Customer is written. Both shapes are documented under All Flows below.
The most common cause specific to this flow is attempting to retrieve a response that OpenAI no longer holds. Because enrichment requests are submitted without long-term storage, a response is retained only briefly after it completes. See the OpenAI Known Limitations article.
Add/Update OpenAI Product TO iPaaS.com
Errors on this flow are returned by OpenAI when the completed enrichment is fetched, or by iPaaS.com when the enriched Product is written. Both shapes are documented under All Flows below.
A cause specific to this flow is a required Product value arriving empty or outside its allowed set. iPaaS.com requires Sku, Name, Type, TrackingMethod, DefaultPrice and Status on a Product, and accepts only Physical or Virtual for Type, Product or Variant for TrackingMethod, and Preorder, Active, Disabled or Discontinued for Status. An instruction that rewrites any of those risks producing a value the write will not accept.
Add/Update OpenAI Message TO iPaaS.com
Prerequisite Transfer Failed
Error message: Error during prerequisite action for MESSAGE during proper hook creation. This will prevent further processing of the transfer request.
Description: the inbound notification was received and its routing details were read, but the Customer or Product transfer it dispatched did not complete. Because that dispatch is a prerequisite, the Message transfer stops as well and the enrichment is not applied. The underlying failure is logged separately and is usually the more useful entry to read.
Resolution: look for the accompanying error on the Customer or Product flow and resolve that — this message reports that a dependent transfer failed, not what went wrong inside it. Confirm the target collection is enabled, then re-submit the record for enrichment. Note that re-running the notification alone is not usually possible, because the response it points at is retained only briefly.
All Flows
OpenAI Request Failed
Error message: Error calling OpenAI [action]: [response returned by OpenAI] (Http Code: [status code])
Description: OpenAI rejected a request or returned an unexpected result. The [action] portion names the operation attempted, [status code] is the HTTP status OpenAI returned, and the middle portion is OpenAI's own response, reproduced as received. Common causes are an API key that has been revoked or lacks the required permission, a model name that the account cannot access, and a malformed request produced by a ModelInstructions value.
Resolution: read the status code and OpenAI's message first, as they identify the cause directly. For a permission or authentication status, confirm the API Key on the subscription is current and carries at least Write permission on the Responses capability. For a model-related message, confirm the OpenAI Model setting names a model the account can use. If the message indicates a problem inside OpenAI rather than with the request, retry the transfer. If it persists and the cause is not apparent, contact iPaaS.com Support at support@ipaas.com.
Connection Validation Failed
Error message: [reason reported by OpenAI]
Description: raised when subscription settings are saved and iPaaS.com cannot establish a connection to OpenAI. The message is the reason OpenAI gave, passed through unchanged. The connection is not established and no transfers run until it is resolved.
Resolution: confirm the API Url is correct and reachable, and that the API Key is current and has not been revoked in the OpenAI console. Because connection validation needs fewer permissions than enrichment does, a key that validates successfully may still be too restricted to run a transfer — confirm it carries at least Write permission on the Responses capability. See the OpenAI Connections and Settings article.
Unexpected Connection Problem
Error message: Unable to reach OpenAI to validate the connection. Check the API Url and API Key on the subscription, then try again.
Description: raised when a connection attempt fails without OpenAI returning any reason that can be reported. This usually indicates a network-level problem between iPaaS.com and OpenAI rather than a configuration mistake, since a rejected key or a bad address normally produces the more specific message above.
Resolution: confirm the API Url is correct, then retry. If the problem persists, check whether OpenAI is reporting a service incident. If neither explains it, contact iPaaS.com Support at support@ipaas.com.