Profile import errors and troubleshooting
Feature availability is part of a phased rollout. Your organization may not see this functionality yet. It will become available when your environment is included in the rollout.
This topic describes the batch states, record-level error codes, HTTP error responses, and common issues you might encounter when using profile import.
Batch states
A batch moves through the following states during its lifecycle:
| State | Description |
|---|---|
QUEUED | The file was uploaded successfully and is waiting to be picked up for processing. |
RUNNING | The batch is being processed. Records are being read, validated, and imported. |
COMPLETED | All records in the batch were processed successfully with zero errors. |
COMPLETED_WITH_ERRORS | Processing finished, but at least one record failed. Download the results file to identify which records failed and why. |
FAILED | The batch failed due to a system error after exhausting all retry attempts. |
The system automatically retries a batch up to 3 times if it encounters a system error during processing. After 3 failed attempts, the batch moves to the FAILED state permanently.
Record-level error codes
When individual records fail during processing, each failed record includes an error code in the results file. The following table describes the error codes and their causes:
| Error code | Cause | Resolution |
|---|---|---|
INVALID_RECORD | The record is malformed. Common causes: malformed JSON, missing or invalid recordType, missing or non-array identifiers, no valid identifier (no provider matching a configured identity rule, or empty id), invalid id format (not a valid UUID), or array values in the contact or extensions fields. | Fix the input record. Verify that recordType is set to profile, identifiers contains at least one valid entry, and the payload does not contain arrays. |
NO_UPDATABLE_FIELDS | The record payload is empty or all fields are null. There is nothing to write to the profile. | Add at least one non-null field to contact or extensions. |
INCONSISTENT_IDENTIFIERS | The record's identifiers resolve to more than one existing profile. The system cannot determine which profile to update. | Review the identifiers in the record. Ensure they consistently point to a single profile. You might need to clean up duplicate profiles or adjust your identifiers. |
WRITE_FAILED | A system error occurred while writing the record to the data store after exhausting all retries. | This is typically a transient error. Re-upload the batch to retry. If the error persists, contact Sitecore Support. |
HTTP error responses
The following table lists the HTTP errors the Profile Import API can return:
| Status code | Endpoint | Cause |
|---|---|---|
400 Bad Request | Upload | The MD5 checksum does not match the uploaded file or the file is empty. |
401 Unauthorized | All | The request does not include a valid API key. |
403 Forbidden | All | The API key is not authorized to perform this operation. |
404 Not Found | Status, Stats, Results | The specified batchId does not exist, or results are not yet available. |
429 Too Many Requests | Upload | Queue limit reached. A batch is already queued or running for your environment. Wait for the current batch to complete before uploading another. |
Retry behavior
Profile import includes automatic retry handling at two levels:
-
Batch-level retries - if a batch encounters a system error during processing, the system automatically retries the batch. The batch returns to the
QUEUEDstate and is picked up again by the scheduler. A batch is retried up to 3 times before it is permanently marked asFAILED.Retries are idempotent. Records that were already processed in a previous attempt are not reprocessed. The system skips them and only processes records that were not completed.
-
Record-level error handling - individual record failures do not stop the batch. If a record fails validation or processing, the system records the error and continues processing the remaining records. You can review all record-level failures by downloading the results file or checking the batch statistics.