# DAM error details

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

All DAM operations are **Beta**. See [REST API Evolution and Compatibility Policy](/rest-api-evolution-and-compatibility-policy) and the [Changelog](/changelog) for explicitly identified breaking changes.

For cross-API status code guidance, see [Error responses](/guides/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)


## Error response format

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:

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

Service-level image and file validation messages carry no field context and are grouped under a generic `error` key. For example, creating either resource with a filename longer than 255 characters (extension excluded) returns:

```json
{
  "validationFailures": {
    "error": ["File name exceeds maximum length of 255 characters"]
  }
}
```

## 400 Bad Request

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

For list operations on either resource, date comparisons in `$filter` must use UTC ISO 8601 timestamps with a `Z` suffix, such as `modifiedOn gt 2026-10-01T08:00:00Z`.

Common causes:

### GET `/images`

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


### POST `/images`

* Missing or invalid `url`
* Unsupported image file extension
* Invalid tag values
* Image URL constraints are not met
* Filename exceeds 255 characters, extension excluded
* The source URL is not reachable or returns a failing HTTP status during download, including an expired signed URL


### GET `/images({reference})`

The current specification does not define `400` for this operation.

### PATCH `/images({reference})`

* 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 replacement keeps the existing image name. The 255-character filename limit for `POST` does not apply to the replacement URL's filename. A source URL that returns a failing HTTP status during download produces `400` with `URL is not accessible…`.

### DELETE `/images({reference})`

The current specification does not define `400` for this operation.

### GET `/files`

* 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


### POST `/files`

* 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)
* Filename exceeds 255 characters, extension excluded
* A failing HTTP status during download, even if the reachability check succeeded


### GET `/files({reference})`

The current specification does not define `400` for this operation.

### PATCH `/files({reference})`

* Missing both `url` and `tags`
* The replacement URL's content is not a file of the current file type
* The documented URL accessibility, extension, size, and tag validation failures


The replacement keeps the existing file name. The 255-character filename limit for `POST` does not apply to the replacement URL's filename. A source URL that returns a failing HTTP status during download produces `400` with `URL is not accessible…`.

### DELETE `/files({reference})`

The current specification does not define `400` for this operation.

## 401 Unauthorized

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:

```http
X-API-KEY: YOUR_API_KEY
```

## 403 Forbidden

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.


## 404 Not Found

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


## 409 Conflict

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

**Images:** `PATCH /images({reference})` and `DELETE /images({reference})` can conflict with active background processing; retry later. For `POST /images`, the documented causes are a duplicate filename or a full image-library quota. Resolve the duplicate or free capacity before retrying.

**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.


## 500 Internal Server Error

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.

A source URL that returns a failing HTTP status, including during download after a successful reachability check, is a `400` validation failure with `URL is not accessible…`. The source specification still documents technical transport failures and download timeouts as possible `500` errors for image operations; inspect the response instead of treating every download problem alike.

## Endpoint summary

| Endpoint | Possible error codes |
|  --- | --- |
| `GET /images` | `400`, `401`, `403`, `500` |
| `POST /images` | `400`, `401`, `403`, `409`, `500` |
| `GET /images({reference})` | `401`, `403`, `404`, `500` |
| `PATCH /images({reference})` | `400`, `401`, `403`, `404`, `409`, `500` |
| `DELETE /images({reference})` | `401`, `403`, `404`, `409`, `500` |
| `GET /files` | `400`, `401`, `403`, `500` |
| `POST /files` | `400`, `401`, `403`, `409`, `500` |
| `GET /files({reference})` | `401`, `403`, `404`, `500` |
| `PATCH /files({reference})` | `400`, `401`, `403`, `404`, `500` |
| `DELETE /files({reference})` | `401`, `403`, `404`, `500` |


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.

## Troubleshooting checklist

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


## Related pages

* [Introduction](/guides/introduction)
* [Authentication](/guides/authentication)
* [Rate limiting](/guides/rate-limiting)
* [Error responses](/guides/error-responses)
* [API reference overview](/apis)