Handling timing issues when creating folders and importing assets with AEM Assets Author API
This article describes how to address intermittent failures when importing assets into newly created folders using the Adobe Experience Manager (AEM) Assets Author API by implementing retry logic to ensure folders are fully available before asset import operations.
Description description
Environments
Adobe Experience Manager (AEM), including AEM as a Cloud Service and other deployment models using the Assets Author API and OpenAPI-based endpoints.
Symptoms
When automating asset imports, an external application:
- Checks if a target folder exists using the Folder Exists (HEAD) API.
- Creates the folder if it doesn’t exist using the Create Folder API.
- Receives a successful folder creation response and a subsequent Folder Exists (HEAD) API call returns HTTP 200.
- Immediately calls the Assets Import API (
/import/fromUrl) to upload an asset. - The import request sometimes fails with HTTP 400 or HTTP 403 errors, such as Cannot resolve folder or other write-related errors.
- In some cases, the Create Folder API returns HTTP 200, but the response payload indicates failure (For example: empty successes array and error message).
Example API requests and responses
Create Folder API response (failure despite HTTP 200):{"operation": "adobe.folders.createFolders","status": 200,"description": "Created folders","data": { "values": { "successes": [ ] } },"errors": [ {"type": "https://api.adobeaemcloud.com/adobe/meta/errors/internal_server_error","title": "Internal Server Error","detail": "Failed to create folder /content/dam/folder1 due to an exception: Unable to commit changes to session."}] ,"warnings": [ ] }
Cause
AEM exhibits eventual consistency after folder creation, resulting in a short delay before the folder is fully available for asset operations. A successful Folder Exists (HEAD) response doesn’t always guarantee immediate readiness for asset imports.
Resolution resolution
Follow the steps below to resolve the issue:
-
After creating a folder, always inspect the Create Folder API response payload:
-
Confirm that the
successesarray contains the expected folder path. -
Check for any errors in the response, even if the HTTP status is 200.
-
-
Don’t immediately call the Assets Import API after folder creation. Instead, implement a bounded retry mechanism:
-
Wait for a short interval (For example: 1 second) before retrying the folder existence check.
-
Retry the check a limited number of times (For example: 2–3 attempts with increasing delays such as 1s, 2s, 4s).
-
Only proceed to call the Assets Import API after the folder existence check consistently returns HTTP 200, and the folder is confirmed to be available (and the folder creation response is successful).
-
-
If the import operation still fails with folder resolution or transient write/access errors, continue retrying for a limited number of attempts before treating it as a final failure.
-
If persistent 403 errors occur, validate permissions and API access configuration for the target path.
Verification: Confirm that the asset import operation succeeds without folder resolution errors after following the above steps.