---
title: "Errors"
description: "Common Imagen API errors and how to fix them: profile mismatches, unsupported or mixed file types, duplicate filenames, incomplete uploads, and trial limits."
canonical: https://api-docs.imagen-ai.com/docs/reference/errors/
last-updated: 2026-08-27
---

# Errors

## Error response format

Every error returns a JSON body together with the matching HTTP status code, so
you can branch on both. There are three response shapes to handle.

**Most errors** - an `error` object with a human-readable `message`. This is the
shape you'll hit for `400`, `401`, `403`, resource `404`s (e.g. a project that
doesn't exist), and `500`. Every message in the [table below](#errors) is
returned as this `message`.

```json
{ "error": { "message": "Project does not exist." } }
```

**Validation errors** - a `422` with the standard FastAPI `detail` array, one
entry per field that failed validation:

```json
{
  "detail": [
    { "loc": ["body", "profile_key"], "msg": "field required", "type": "value_error.missing" }
  ]
}
```

**Unknown route** - a `404` for a path the API doesn't define returns a plain
`detail` string:

```json
{ "detail": "Not Found" }
```

For contrast, successful responses wrap their payload in a `data` object:
`{ "data": { ... } }`. So a reliable check is: treat the response as an error
whenever `error` or `detail` is present, and read the message from
`error.message` (or `detail`).

## Errors you might hit

These are the errors you're most likely to encounter, with the cause and the fix
for each.

| Status | Message | Cause | Fix |
| --- | --- | --- | --- |
| 400 | `Profile key ... not found.` | Profile ID isn't yours or has been deleted. This applies to the profile-based flow only. | Re-list with `GET /v1/profiles` and pick a valid one. |
| 400 | `Unable to send raw images with JPEG profile` | You picked a JPEG profile but uploaded RAW images. | Use a JPEG profile for JPEG uploads, or a RAW profile for RAW uploads. |
| 400 | `Unable to send JPEGs images with raw profile` | You picked a RAW profile but uploaded JPEG images. | Use a JPEG profile for JPEG uploads, or a RAW profile for RAW uploads. |
| 400 | `file ... is not supported. supported files types are ...` | A file has an unsupported extension. | Upload only [supported formats](/docs/onboarding#formats). |
| 400 | `Invalid combination of file types ...` | You mixed JPEG with RAW/DNG in one project. | Keep one project all-JPEG, all-RAW, or RAW+DNG. See [supported formats](/docs/onboarding#formats). |
| 400 | `File "..." appears N times.` | Two uploaded files share a filename. | Give every file a [unique name](/docs/reference/uploading#filenames) before requesting upload links. |
| 400 | `Upload Incomplete: X out of Y files are missing.` | Fewer files reached S3 than you requested links for. | Retry failed PUTs before calling `/edit`. |
| 400 | `No images were uploaded for this project.` | You called `/edit` before any files reached S3. | Confirm all PUTs succeeded before calling `/edit`. |
| 404 | `Project not found` | The Smart Editing `project_uuid` doesn't exist. | Re-check the UUID returned by `POST /v1/i2i/projects`. |
| 403 | `You don't have permission to access this project` | The Smart Editing project belongs to another account. | Use a UUID you own. |
| 400 | `This project exceeds the free edits in your trial.` | Trial-photo cap reached. Real estate accounts have a 250-photo limit. | Subscribe at [imagen-ai.com/pricing](https://imagen-ai.com/pricing/). |