Error Recovery Tips

The Customer-Present Cloud API has several responses associated with it with regards to error messages. Use the following to recover more quickly based on the response message associated with the error.

Device Management

Message/Issue	Explanation and Potential Recovery
The Problem: "API key required."	You are not sending an API key for authentication or have not included 'Bearer' where applicable in your header. The Solution: Use an existing API key (found on the Security Keys page in a Merchant Gateway Account), or create one. Send a valid Merchant API key in the Authorization header as documented.
The Problem: "Missing/Invalid Authentication"	You are not passing 'Bearer' and your merchant API key into the Authorization header of your request. The Solution: Check that your authorization header request does not include anything other than the word 'Bearer' and your merchant account's API Key. No other words or credentials should be present. See our documented example requests for Registration/Deregistration and Estate Management for more information.
The Problem: "Missing required field: 'registration code''	You are not passing the required 'registrationCode' field in the body of your request or are not passing a value into it during device registration. The Solution: Use the documented parameter in the body of your request and ensure you are passing a value.
The Problem: "Missing required field: 'poi device id'"	You are not passing the required POI Device ID in your deregistration request. The Solution: Ensure you are passing a value in with the /devices/deregister endpoint.
The Problem: Encrypted Device service not available	The gateway account you are attempting to process on does not have the correct 'Encrypted Devices' service enabled on it. The Solution: Contact the provider of the gateway account to have them enable this service for you.
The Problem: "Invalid registration code. Please try again."	Occurring exclusively on the registration request, this means that the code provided in the request was not valid at the time of the request. Registration codes expire every 15 minutes, so using an old code will not be possible. The Solution: Look at the POI Device screen of the unregistered internet-connected POI Device and use the currently visible code on the screen.
The Problem: "Device Deregistration Unsuccessful" or "Invalid poi device id"	Whether you are attempting to deregister a device or query on it, you are not passing in the correct POI Device ID value. The Solution: Query against the /list endpoint without specifying an ID to get a list of all valid POI Devices and resend your request once you acquire the valid ID.
The Problem: "I am seeing my device display 'Registered POI Device' instead of the nickname I provided."	The Solution: Check that you are sending the proper parameter 'deviceNickname' in during registration. If you are not, the default 'Registered Device' appears instead. You can deregister your device, and re-register it with the proper parameter/nickname value.
The Problem: "I am not seeing any devices in the poiDeviceID object when I ping the /list endpoint."	The Solution: If the response contains no data, this means there are no registered (or deregistered) devices on the account at all. Check that you are using the correct API key for the account you wish to query against.

Processing

Message	Explanation and Potential Recovery
The Problem: "API key required."	You are not likely sending an API key for authentication. The likely culprit is the use of username/password which is not supported when using a POI Device. The Solution: Use an existing API key (found on the Security Keys page in a Merchant Gateway Account), or create one. Use the 'security_key' variable to pass it in and omit username/password credentials.
The Problem: "Only one authentication method may be used."	You are likely sending two types of credentials in your request and must only use one. The Solution: When processing with a POI device, use the 'security_key' variable via API to authenticate. Use of the username/password credential set is not supported.
The Problem: Encrypted Device service not available	The gateway account you are attempting to process on does not have the correct 'Encrypted Devices' service enabled on it. The Solution: Contact the provider of the gateway account to have them enable this service for you.
The Problem: "Invalid poi_device_id."	The value being provided in the poi_device_id variable is incorrect or invalid. The Solution: Query your POI Device estate via API or log into the Merchant Control Panel and check 'Registered Devices' in the License Manager for valid/registered POI Device IDs.
The Problem: "Communication with the POI device has timed out. Please restart transaction."	The transaction has exceeded the 300 second timeout limit and the transaction has been cancelled. The Solution: The transaction must be restarted by sending a new transaction request to the POI Device.
The Problem: "The POI device already in use. Please complete the current transaction and try again."	The physical device (as represented by the POI Device ID) is currently in the middle of a transaction and cannot be used. The Solution: Target a different POI Device ID or cancel the transaction in progress if necessary.
The Problem: "The transaction was cancelled on the POI device. Please restart transaction."	The transaction was cancelled by the user OR the POI Device itself and will not be successful. The Solution: Restart the transaction by sending a new transaction request to the POI Device.

Asynchronous Status Polling

Message	Explanation and Potential Recovery
The Problem: "API key required."	You are not sending an API key for authentication or have not included 'Bearer' where applicable in your header. The Solution: Use an existing API key (found on the Security Keys page in a Merchant Gateway Account), or create one. Send a valid Merchant API key in the Authorization header as documented.
The Problem: "Missing/Invalid Authentication"	You are not passing 'Bearer' and your merchant API key into the Authorization header of your request. The Solution: Check that your authorization header request does not include anything other than the word 'Bearer' and your merchant account's API Key. No other words or credentials should be present. See our documented example requests for Registration/Deregistration and Estate Management for more information.
The Problem: "Platform Id or API Key not found"	Either the platform ID value you've provided to the polling API is old or invalid, your API key is invalid, or your API key in use was not the key that initiated the transaction. The Solution: Check that your API key and platform ID provided match the API key used and platform ID value received in the original asynchronous request. If you are polling against an old platform ID, use the Query API to retrieve historical information on transactions. The AsyncStatus API is meant for transactions happening in the moment vs a reporting API.

Note: The vast majority of these errors will be accompanied by a REFID code which you should provide to support if troubleshooting is necessary. If you cannot recover from an error for any reason, contact Customer Support for assistance.

For AsyncStatus API issues, provide the errorRefUUID value to support for troubleshooting.

See our documented example requests for the AsyncStatus API for more information.