DAM error details

This page lists DAM REST API error details for image and file operations.

For cross-API status code guidance, see Error responses.

The DAM REST API uses standard HTTP status codes to indicate whether a request succeeded or failed. Images and files share the same error schemas and general patterns, but differ in which status codes apply to which operation — most notably, only images are queued for background processing, so only image writes can return a 409 for that reason.

When an operation fails, first check:

• The X-API-KEY header
• Path and query parameter values
• Whether the target image or file exists
• Whether the image is currently being processed (files are never queued for processing)

DAM error response bodies depend on the status code and operation, and are shared between images and files. The OpenAPI specification defines these DAM-specific error schemas:

• ValidationFailureRepresentation for validation failures.
• UnauthorizedRepresentation for missing or invalid API keys.
• ForbiddenRepresentation for authenticated requests that are not allowed to perform the operation.
• ConflictRepresentation for state conflicts, such as image processing conflicts, or duplicate file names.
• ErrorRepresentation for unexpected processing errors.

Example:

{
  "validationFailures": {
    "url": [
      "The image URL must be a valid HTTP or HTTPS URL."
    ]
  }
}

File validation failures use the same envelope, but since file-level messages carry no field context they are grouped under a generic error key instead of a field name:

{
  "validationFailures": {
    "error": ["URL is required"]
  }
}

The request is syntactically valid HTTP, but the API cannot process it because one or more values are invalid.

Common causes:

• Invalid $filter syntax
• Unsupported field in $orderby
• Invalid pagination values such as $top or $skip

• Missing or invalid url
• Unsupported image file extension
• Invalid tag values
• Image URL constraints are not met

The current specification does not define 400 for this operation.

• Missing both url and tags
• The replacement URL's content is not an image of the current file type — the filename itself is no longer required to match; only the content type must
• Unsupported image file extension
• Invalid tag values

The current specification does not define 400 for this operation.

• Invalid $filter syntax
• A field named in $filter or $orderby that is not queryable — only reference, numLinks, status, modifiedOn, fileType, and createdOn are supported
• A negative $skip, or a $top outside 1–100

• Missing or invalid url (not absolute, wrong scheme, over 2048 characters)
• No file extension in the URL, or an unsupported extension
• The URL host is not publicly routable, or the URL is not reachable
• The uploaded content does not match the file type its extension announces, or matches no known file type
• File exceeds the 250 MB size limit
• Invalid tag values (empty, whitespace-only, or containing a comma)

The current specification does not define 400 for this operation.

• Missing both url and tags
• The replacement URL's content is not a file of the current file type
• Any of the url or tags validation failures documented for POST /files

The current specification does not define 400 for this operation.

The request does not include a valid API key.

Typical causes:

• Missing X-API-KEY header
• Empty API key value
• Invalid API key

Example request header:

X-API-KEY: YOUR_API_KEY

The request includes a valid API key, but the key is not allowed to perform the requested DAM operation.

This can happen when:

• The API key does not have access to DAM operations.
• The API key has read access but not write access for create, update, or delete operations.

The requested image or file does not exist or cannot be found for the current tenant.

This can happen when:

• The reference (filename) is wrong
• The image or file has already been deleted
• The image or file does not belong to the current tenant context

The cause of a 409 differs between images and files — they are not interchangeable, and only images are ever locked by background processing.

Images: the operation cannot be completed because the image is currently being processed. Relevant for POST /images, PATCH /images({reference}), and DELETE /images({reference}). This usually means the image is temporarily locked by an active processing workflow. Retry later.

Files: relevant only for POST /files, for two unrelated reasons — a file is never processed in the background, so PATCH /files({reference}) and DELETE /files({reference}) never return a 409:

• A file with the same filename (reference) already exists for this tenant.
• The tenant has reached its file-library quota. Deleted files do not count towards the quota; delete unused files to free capacity, or contact Sales Layer to raise the limit. The image and file libraries have separate quotas.

The server encountered an unexpected error while processing the request.

Typical causes include:

• Network connectivity issues
• Storage service unavailable
• Database errors

A 500 response usually indicates a temporary or server-side problem rather than a client-side validation issue.

Note that PATCH /files({reference}) and DELETE /files({reference}) do not document 409 — unlike their image counterparts, since files are never queued for background processing.

Before retrying a failed request, verify:

• The X-API-KEY header is present and valid
• The endpoint path is correct
• The image or file reference (filename) is correct when using GET, PATCH, or DELETE
• Create and replacement URLs are public HTTP or HTTPS URLs with supported file extensions for the resource type (images and files accept different, and different-sized, sets of extensions)
• Query parameters are supported and correctly formatted

• Introduction
• Authentication
• Rate limiting
• Error responses
• API reference overview