Erros

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.

ChaveTipoDescrição
requestIdstringIdentificador de rastreamento desta requisição. Ao contatar o suporte, informe este valor para que a requisição correspondente seja localizada rapidamente.
sys.typestringClassificação do erro. Indica as grandes categorias como Unauthorized, Forbidden, NotFound, Unprocessable, Conflict, TooManyRequest, entre outras.
sys.codestringCódigo de erro detalhado (por exemplo, WGL409005). Use este valor quando ramificar o tratamento por código.
sys.timestampintegerMomento em que o erro ocorreu (epoch millis).
reasonstringMotivo da falha em linguagem legível por humanos.
suggestionstringDica que ajuda a resolver o problema.
detailsobject (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ódigoClassificaçãoSignificadoSituação comum
WGL401001UnauthorizedToken inválidoO token Bearer de Authorization expirou ou está incorreto.
WGL403001ForbiddenSem permissãoO papel de quem fez a chamada não permite essa operação. A requisição barrada não pelo papel, mas pelo ponto de chamada, é devolvida com o WEB403001 abaixo.
WEB403001ForbiddenSem permissão de acesso ao recursoA própria requisição não foi autorizada e por isso foi recusada. Quando a chamada é feita com um Delivery Access Token ou um Space Access Token, a requisição barrada na verificação de allowedReferrers é devolvida com este código. É um código diferente do WGL403001, que significa que o papel não tem a permissão.
WGL403012ForbiddenRecurso suspenso por excesso de usoO uso de transferência ou de espaço de armazenamento da Organization ultrapassou a franquia incluída no plano, e o recurso correspondente foi suspenso (por exemplo, API de leitura, upload de novo Media, implantação de Web Hosting). Diferentemente do WGL429001, que é um limite de quantidade, esta é uma suspensão por excesso de uso. Para as condições de reativação, consulte Planos.
WGL404001NotFoundRecurso inexistente ou excluídoVocê consultou com um sys.id incorreto, ou chamou um recurso ainda não configurado (por exemplo, domínio personalizado não conectado).
WGL400006BadRequestValor do corpo viola as regras de validaçãoVocê enviou o corpo com uma chave de campo ou um tipo incorreto. Os itens que violaram as regras são incluídos em details.errors.
WEB400014BadRequestCampo de ordenação ausente no selectVocê não incluiu no select um campo usado no order. Todos os campos usados na ordenação também precisam estar no select (consulte Parâmetros de consulta comuns).
WGL409005ConflictO recurso foi modificado nesse meio-tempoO cabeçalho X-Weegloo-Version está ausente ou difere da versão atual (consulte Convenções).
WGL422007UnprocessableNão é possível arquivar por estar publicadoPara arquivar um Content ou um Media, é preciso anular a publicação primeiro.
WGL422009UnprocessableNão é possível excluir por estar publicadoPara excluir um Content ou um Media publicado, é preciso anular a publicação primeiro.
WGL429001TooManyRequestLimite do plano excedidoA 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.
  • Planos: os critérios por plano e a forma de reativação para WGL403012 (suspensão por excesso de uso) e WGL429001 (limite de quantidade).