Weegloo Docs - 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 will run into most often in one place.

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.

{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "tcq4V2Xb", "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.

{
  "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

The following are the error codes you encounter most often.

Code	Classification	Meaning	Common situation
`WEB401001`	`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.
`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`.
`WGL409005`	`Conflict`	The resource was modified in the meantime	The `X-Weegloo-Version` header is missing or differs from the current version (see Conventions).
`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.

Conventions: The X-Weegloo-Version concurrency rule for avoiding WGL409005.
System properties (sys): The publish status (status) and the lifecycle that WGL422007 and WGL422009 point to.

Error response format

Common codes

Related documents