Error codes and what they mean

A reference for the common error categories you may see when investigating failed events in the Control Panel.

This page lists the error types you may see on a failed event in the Control Panel, what each one means and what to do next. Errors fall into three groups: validation errors (the data does not meet the destination's requirements), connection errors (HC could not reach the destination) and business rule errors (the destination rejected the event under its own rules).

Validation errors

Error	What it means	Fix in the Control Panel?	What to do
Missing required field	A field the destination system requires was not present in the source data. The error message names the field.	Sometimes	If the value exists in the source system but was not included (for example a phone number), add it in the Control Panel and resend. If it is not available in the source data, contact HC; a configuration change may be needed.
Invalid value	A field contains a value the destination does not accept: an unrecognised currency code, a tax code that does not exist in the ERP, text in a numeric field, or a string over the maximum length.	Sometimes	Correct the value and resend if you can. If the problem is in the mapping logic, contact HC.
Duplicate record	An event with the same reference has already been processed.	No	Check whether the record exists in the destination. If it does, no action is needed. If it does not, contact HC.
Record not found	The event refers to a record that does not exist in the destination, for example a return for an order HC did not create in the ERP, or a missing customer record.	No	Contact HC.

Connection errors

Error	What it means	Fix in the Control Panel?	What to do
Timeout	The destination did not respond within the expected time limit.	No; HC retries automatically	If timeouts recur or the destination is consistently slow, contact HC.
Authentication error	HC's connection to the destination has expired or been revoked; the API credentials usually need refreshing.	No	Contact HC immediately. This error affects every event on the stream until it is resolved.
Rate limit	The destination rejected the request because too many API calls were made in a short period.	No; HC retries with backoff	If rate limiting persists over a long period, contact HC.
Destination unavailable	The destination returned an error saying it is down or unreachable.	No; HC retries automatically	If the destination is back online and events are still failing, contact HC.

Business rule errors

Error	What it means	Fix in the Control Panel?	What to do
Business rule rejection	The destination rejected the event because it violated one of its own internal validation rules. These are specific to your destination system's configuration.	No	Contact HC with the event ID and the full error message.

Note. If your error is not listed here, see I received an alert — what now? for general guidance, or contact HC with the event ID and the full error text. To fix and resend an event, see How to fix and resend a failed event.

Was this helpful?

Still need help? Ask the team