> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecomwize.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP status codes and error responses returned by the EcomWize API.

All API errors return a JSON response with three fields:

```json theme={null}
{
  "error": "Short error name",
  "message": "Detailed explanation of what went wrong and how to fix it.",
  "status": 400
}
```

## Status codes

| Status | Error                   | When it happens                                                                           |
| ------ | ----------------------- | ----------------------------------------------------------------------------------------- |
| `200`  | --                      | Request succeeded.                                                                        |
| `201`  | --                      | Page created successfully (duplicate-and-fill).                                           |
| `400`  | Invalid JSON            | Request body is not valid JSON. Check for unescaped quotes or syntax errors.              |
| `400`  | Invalid sections format | The `sections` field is an array instead of an object. Use `section_1`, `section_2` keys. |
| `400`  | Empty sections          | The `sections` object has no keys. Send at least one section.                             |
| `400`  | Validation failed       | A section key is out of range, or you sent a style/layout field. Details are included.    |
| `401`  | Authentication failed   | Missing, invalid, or revoked API key.                                                     |
| `402`  | Payment required        | Your subscription has a payment issue. Update your billing in the dashboard.              |
| `403`  | Read-only API key       | You used a read-only key on a write endpoint. Create a key with Full access.              |
| `403`  | Page limit reached      | Your plan's page limit is reached. Upgrade to create more pages.                          |
| `404`  | Page not found          | The page ID does not exist or does not belong to your account.                            |
| `413`  | Request body too large  | The request body exceeds 512KB. Send less content per request.                            |
| `429`  | Rate limit exceeded     | Too many requests. Wait and retry. Check the `Retry-After` header.                        |
| `500`  | Internal server error   | Something went wrong on our end. Try again or contact support.                            |

## Validation errors

When the API rejects specific fields, the response includes a `details` array with one message per issue:

```json theme={null}
{
  "error": "Validation failed",
  "message": "Some sections could not be filled. This page has 12 sections (section_1 to section_12).",
  "details": [
    "section_15 is out of range (section_1 to section_12)",
    "section_2 (hero01): style/layout keys not allowed via API: backgroundColor, headingSize"
  ],
  "status": 400
}
```

### Common validation issues

<AccordionGroup>
  <Accordion title="Section out of range">
    You referenced a section number that does not exist. Call `GET /api/v1/pages/{page_id}` to see available sections.

    ```json theme={null}
    "section_15 is out of range (section_1 to section_12)"
    ```
  </Accordion>

  <Accordion title="Style/layout keys rejected">
    You sent a field like `backgroundColor` or `headingSize` which is a style field, not content. The API only accepts text, media, and link fields.

    ```json theme={null}
    "section_2 (hero01): style/layout keys not allowed via API: backgroundColor, headingSize"
    ```
  </Accordion>

  <Accordion title="Invalid section key">
    Your section key does not follow the `section_N` format.

    ```json theme={null}
    "\"hero\" is invalid. Use section_1, section_2, etc."
    ```
  </Accordion>
</AccordionGroup>

## Rate limit headers

When you hit a rate limit, the response includes these headers:

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window.   |
| `X-RateLimit-Remaining` | Requests remaining in the current window. |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets.    |
| `Retry-After`           | Seconds to wait before retrying.          |

```json theme={null}
{
  "error": "Rate limit exceeded. Try again later.",
  "status": 429
}
```

<Tip>
  If you are building an automation that runs in a loop, add a short delay between requests to stay within the rate limit.
</Tip>