> 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`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.aihomedesign.com/resources/error-codes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.