# Errors

When a request fails, WEEGLOO returns a consistently shaped error body together with an HTTP status code. The shape of the response body is the same regardless of which API (CMA, CDA, ACMA, ACDA, Upload, Auth) the failure came from. So once you know how to handle a single format, you can branch on every error the same way. This page gathers that common format and the error codes you run into most often in one place.

## Error response format {#error-response-format}

An error body looks like the following. The response below is what you get when you read a *WebHosting* that does not exist.

```json
{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } }
  },
  "reason": "WebHosting(...) has been deleted or does not exist.",
  "suggestion": "Please verify WebHosting and try again."
}
```

The meaning of each key is as follows.

| Key | Type | Description |
|---|---|---|
| `requestId` | string | The trace identifier for this request. Passing this value along when you contact support lets them find the request quickly. |
| `sys.type` | string | The error classification. It indicates the broad category, such as `Unauthorized`, `Forbidden`, `NotFound`, `Unprocessable`, `Conflict`, or `TooManyRequest`. |
| `sys.code` | string | The detailed error code (e.g. `WGL409005`). Use this value when you branch at the code level. |
| `sys.timestamp` | integer | The time the error occurred (epoch millis). |
| `reason` | string | The human-readable failure reason. |
| `suggestion` | string | A hint to help resolve it. |
| `details` | object (optional) | Additional information. It holds things like a `Refer` pointing to the related resource, or a list of validation error items (`errors`). It may be absent depending on the kind of error. |

Branch at whichever level you need: `sys.type` (the broad category) or `sys.code` (the detailed code). Even for the same `sys.type`, a different `sys.code` means a different cause, so branch on `sys.code` when you need precise handling.

When validation fails, `details.errors` carries the offending items. The following is the response from a validation failure caused by putting a property that is not in the schema into the body.

```json
{
  "requestId": "yJ8KpQ2mWtnLrZ4Xv7BcEadfh3sNuMvKbGT5Pq9wRsx",
  "sys": {
    "id": "Lm2Nq9Tr8KdW4xZc",
    "type": "BadRequest",
    "code": "WGL400006",
    "timestamp": 1781776000000
  },
  "details": {
    "errors": [
      { "path": "", "message": "property 'X' is not defined in the schema", "property": "X" }
    ]
  },
  "reason": "Some values do not satisfy validation rules.",
  "suggestion": "Please check the request body and try again."
}
```

Each item in `details.errors` carries the offending location (`path`), a description (`message`), and the related property name (`property`). If there are several items, there is one for each offending value.

## Common codes {#common-codes}

The following are the error codes you encounter most often.

| Code | Classification | Meaning | Common situation |
|---|---|---|---|
| `WGL401001` | `Unauthorized` | The token is not valid | The `Authorization` Bearer token has expired or is wrong. |
| `WGL403001` | `Forbidden` | No permission | The caller's role does not allow that operation. A request blocked because of the call site rather than the role comes back as `WEB403001` below. |
| `WEB403001` | `Forbidden` | No permission to access the resource | The request itself was not authorized, so it was rejected. A call made with a [Delivery Access Token](/api/reference/cma/delivery-access-token.md#referrer-enforcement) or a [Space Access Token](/api/reference/cma/space-access-token.md#referrer-enforcement) that fails the `allowedReferrers` check comes back with this code. It is a different code from `WGL403001`, which means the role has no permission. |
| `WGL403012` | `Forbidden` | The feature is suspended due to over-usage | The *Organization*'s transfer or storage usage has exceeded the plan's included allowance, so the feature has been suspended (e.g. read APIs, new *Media* uploads, *Web Hosting* deployments). Unlike `WGL429001`, which is a count limit, this is a suspension for exceeding usage. See [Pricing](/pricing/pricing.md#over-limit) for how to lift it. |
| `WGL404001` | `NotFound` | The resource is missing or deleted | You read with a wrong `sys.id`, or you called a feature that is not set up yet (e.g. no custom domain connected). |
| `WGL400006` | `BadRequest` | A body value violates a validation rule | You sent the body with a wrong field key or type. The offending items are carried in `details.errors`. |
| `WEB400014` | `BadRequest` | A sort field is missing from `select` | You did not put a field used in `order` into `select`. Every field used for sorting must also be included in `select` (see [Common query parameters](/api/reference/common/query-parameters.md#parameters)). |
| `WGL409005` | `Conflict` | The resource was modified in the meantime | The `X-Weegloo-Version` header is missing or differs from the current version (see [Conventions](/api/reference/common/conventions.md)). |
| `WGL422007` | `Unprocessable` | Cannot archive because it is published | To archive a *Content* or *Media*, you must unpublish it first. |
| `WGL422009` | `Unprocessable` | Cannot delete because it is published | To delete a published *Content* or *Media*, you must unpublish it first. |
| `WGL429001` | `TooManyRequest` | Plan limit exceeded | The number of created resources such as *Organization* or *Space* has exceeded your current plan limit. Upgrading the plan raises the limit. |

The codes above are a frequently seen subset. Beyond these, there may be more codes depending on the operation and resource. Whatever code you get, identify the broad category from `sys.type`, and check the specific cause and resolution direction from `reason` and `suggestion`.

## Related documents {#related-documents}

- [Conventions](/api/reference/common/conventions.md): The `X-Weegloo-Version` concurrency rule for avoiding `WGL409005`.
- [System properties (sys)](/api/reference/common/system-properties.md): The publish status (`status`) and the lifecycle that `WGL422007` and `WGL422009` point to.
- [Pricing](/pricing/pricing.md#over-limit): The per-plan thresholds and how to lift `WGL403012` (over-usage suspension) and `WGL429001` (count limit).