Weegloo Docs

Quando uma requisição falha, a WEEGLOO devolve um corpo de erro com formato consistente junto com um código de status HTTP. O formato do corpo da resposta é o mesmo, independentemente de em qual API (CMA, CDA, ACMA, ACDA, Upload, Auth) a falha ocorreu. Por isso, ao saber lidar com um único formato, você consegue tratar todos os erros com a mesma lógica de ramificação. Esta página reúne num só lugar esse formato comum e os códigos de erro que você encontra com mais frequência.

Formato da resposta de erro

O corpo de erro tem o formato a seguir. Abaixo está a resposta recebida ao consultar um WebHosting inexistente.

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

O significado de cada chave é o seguinte.

Chave	Tipo	Descrição
`requestId`	string	Identificador de rastreamento desta requisição. Ao contatar o suporte, informe este valor para que a requisição correspondente seja localizada rapidamente.
`sys.type`	string	Classificação do erro. Indica as grandes categorias como `Unauthorized`, `Forbidden`, `NotFound`, `Unprocessable`, `Conflict`, `TooManyRequest`, entre outras.
`sys.code`	string	Código de erro detalhado (por exemplo, `WGL409005`). Use este valor quando ramificar o tratamento por código.
`sys.timestamp`	integer	Momento em que o erro ocorreu (epoch millis).
`reason`	string	Motivo da falha em linguagem legível por humanos.
`suggestion`	string	Dica que ajuda a resolver o problema.
`details`	object (opcional)	Informações adicionais. Contém um `Refer` que aponta para o recurso relacionado, a lista de itens de erro de validação (`errors`), entre outros. Pode estar ausente dependendo do tipo de erro.

O tratamento por ramificação é feito por sys.type (grande categoria) ou por sys.code (código detalhado), na granularidade que você precisar. Mesmo com o mesmo sys.type, um sys.code diferente significa causa diferente; por isso, quando precisar de um tratamento preciso, baseie-se no sys.code.

Quando a validação falha, os itens que violaram as regras são incluídos em details.errors. Abaixo está a resposta de uma falha de validação causada por incluir no corpo uma propriedade que não existe no schema.

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

Cada item de details.errors contém a localização que violou a regra (path), a descrição (message) e o nome da propriedade relacionada (property). Quando há vários itens, há um item para cada valor que violou as regras.

Códigos que você encontra com frequência

A seguir estão os códigos de erro que você encontra com mais frequência.

Código	Classificação	Significado	Situação comum
`WEB401001`	`Unauthorized`	Token inválido	O token Bearer de `Authorization` expirou ou está incorreto.
`WGL403001`	`Forbidden`	Sem permissão	O Role de quem fez a chamada não permite essa operação.
`WGL404001`	`NotFound`	Recurso inexistente ou excluído	Você consultou com um `sys.id` incorreto, ou chamou um recurso ainda não configurado (por exemplo, domínio personalizado não conectado).
`WGL400006`	BadRequest	Valor do corpo viola as regras de validação	Você enviou o corpo com uma chave de Field ou um tipo incorreto. Os itens que violaram as regras são incluídos em `details.errors`.
`WGL409005`	`Conflict`	O recurso foi modificado nesse meio-tempo	O cabeçalho `X-Weegloo-Version` está ausente ou difere da versão atual (consulte Convenções).
`WGL422007`	`Unprocessable`	Não é possível arquivar por estar publicado	Para arquivar um Content ou um Media, é preciso anular a publicação primeiro.
`WGL422009`	`Unprocessable`	Não é possível excluir por estar publicado	Para excluir um Content ou um Media publicado, é preciso anular a publicação primeiro.
`WGL429001`	`TooManyRequest`	Limite do plano excedido	A quantidade de recursos criados, como Organization e Space, ultrapassou o limite do plano atual. Ao subir de plano, o limite aumenta.

Os códigos acima são apenas alguns dos mais frequentes. Além desses, pode haver muitos outros códigos dependendo da operação e do recurso. Qualquer que seja o código recebido, identifique a grande categoria pelo sys.type e confira a causa concreta e a direção da solução pelos campos reason e suggestion.

Convenções: regra de concorrência com X-Weegloo-Version para evitar WGL409005.
Propriedades do sistema (sys): o estado de publicação (status) e o ciclo de vida ao qual WGL422007 e WGL422009 se referem.

Formato da resposta de erro

Códigos que você encontra com frequência

Documentos relacionados