> For the complete documentation index, see [llms.txt](https://doc.aihomedesign.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.aihomedesign.com/resources/error-codes.md).

# Error Codes

All API errors return a JSON body with an `error` field describing what went wrong.

```json
{ "error": "...", "key": "api_error_..." }
```

***

### HTTP Status Codes

| Status | Name                 | Common causes                                                                                                         |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `400`  | Bad Request          | Missing required field; invalid value for an enum field; wrong asset role                                             |
| `401`  | Unauthorized         | `x-api-key` header is missing or the key is invalid                                                                   |
| `403`  | Forbidden            | API key is valid but your plan does not include access to this tool or endpoint                                       |
| `404`  | Not Found            | The order, process, project, or asset ID does not exist                                                               |
| `422`  | Unprocessable Entity | `asset_map` key does not match the tool's input spec; widget slug is invalid; item slug does not belong to the widget |

***

### Debugging Tips

**401 on every request**

* Check that the header name is exactly `x-api-key` (all lowercase)
* Check that the value is the full key with no extra spaces

**403 on a specific tool**

* Your plan may not include that tool — contact <support@aihomedesign.com>

**422 on process creation**

* Double-check that the `asset_map` key matches the tool's input slot slug exactly (e.g. `tool-virtual-staging-input-image`)
* Double-check that each widget slug and item slug are correct for the tool you are using — see the Tool Reference

**Process stuck in `pending` or `processing`**

* Wait a few minutes — complex tools take longer
* If it stays `failed`, retry the process or contact support with the `process_id`