Erros

Toda resposta de erro tem o mesmo corpo JSON:

{
  "code": "hook_not_found",
  "message": "Não encontramos esse webhook. Confira o link ou gere um novo no app.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#hook_not_found"
}

code é estável: use-o no código. O message é para uma pessoa ler.
message vem na língua do cabeçalho Accept-Language (português, espanhol ou inglês). Sem o cabeçalho, em português.
docs aponta para a seção desta página com o mesmo nome do code.
O 429 leva também retry_after.

Status	`code`	Quando
404	`hook_not_found`	Id ou token errado, webhook ou canal apagado
404	`message_not_found`	Mensagem que não é do webhook
410	`hook_paused`	Webhook pausado
413	`payload_too_large`	Corpo acima de 16 KB
422	`payload_unrecognized`	Nenhum formato reconhecido
422	`payload_invalid`	JSON quebrado ou campo inválido
429	`rate_limited`	Passou da taxa de envio
500	`internal`	Erro do nosso lado

`hook_not_found`

404. O link não leva a nenhum webhook. A resposta é a mesma para id errado e token errado, para não confirmar que um id existe.

{
  "code": "hook_not_found",
  "message": "Não encontramos esse webhook. Confira o link ou gere um novo no app.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#hook_not_found"
}

Causas: o link foi copiado pela metade, o webhook foi apagado, o token foi trocado com Gerar novo link, o canal foi apagado, as Integrações estão desligadas na plataforma, ou o sufixo da URL não existe (só /discord, /slack e /betterstack).

O que fazer: confira o link inteiro. Se ele não aparece mais no app, gere um novo em Integrações e atualize a ferramenta.

`message_not_found`

404. Em PATCH ou DELETE de uma mensagem, o id não existe, é de uma pessoa, ou é de outro webhook.

{
  "code": "message_not_found",
  "message": "Essa mensagem não existe ou não é deste webhook.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#message_not_found"
}

O que fazer: use o id que a resposta de ?wait=true devolveu. Um webhook só mexe nas mensagens que ele mesmo mandou.

`hook_paused`

410. Quem gerencia a comunidade pausou o webhook.

{
  "code": "hook_paused",
  "message": "Este webhook está pausado. Quem gerencia a comunidade pode retomá-lo.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#hook_paused"
}

O que fazer: peça para quem gerencia a comunidade usar Retomar no detalhe do webhook. Reenviar não adianta enquanto ele estiver pausado.

`payload_too_large`

413. O corpo passa de 16 KB.

{
  "code": "payload_too_large",
  "message": "O corpo passa de 16 KB. Mande menos texto.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#payload_too_large"
}

O que fazer: mande só o essencial. O cartão aceita título, corpo e até 6 campos: um log inteiro não cabe, mande o resumo e um link (Limites).

`payload_unrecognized`

422. O JSON chegou, mas não tem os campos do formato esperado: com um sufixo (/discord, /slack, /betterstack), os campos daquele formato; na URL sem sufixo, nenhum formato casou (a detecção segue a ordem GGspeak, Discord, Slack).

{
  "code": "payload_unrecognized",
  "message": "Não reconhecemos esse formato. Mande text ou card, ou o corpo do Discord ou do Slack.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#payload_unrecognized"
}

Na URL sem sufixo, o corpo precisa ser um objeto JSON com card ou key (GGspeak), content ou embeds (Discord), ou text, attachments ou blocks (Slack). Com o sufixo, vale o formato dele: /betterstack pede o corpo do incidente (data.attributes). O corpo do Better Stack só é lido na URL com /betterstack.

O que fazer: use um dos formatos. Se a ferramenta manda o JSON dela, que o GGspeak não conhece, ponha uma etapa no meio que monte um text ou um card.

`payload_invalid`

422. O corpo não é um JSON válido, ou um campo está fora do que o GGspeak aceita. O message diz qual campo e o motivo.

{
  "code": "payload_invalid",
  "message": "Confira o campo card.state: use alert, warn, ok ou info.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#payload_invalid"
}

JSON quebrado volta como “O corpo não é um JSON válido.” Os motivos de campo:

Motivo	Quando
precisa ser um objeto	`card` não é um objeto
precisa ser texto	`text`, `key` ou `card.body` não é texto
precisa ser uma lista	`card.fields` não é uma lista
cada campo precisa de name e value em texto	Um item de `card.fields` sem `name` ou `value`
use alert, warn, ok ou info	`card.state` com outro valor
falta title	`card.title` vazio ou ausente
falta text ou card	Formato GGspeak sem `text` nem `card`
falta content ou embeds	`content` ou `embeds` presente, mas sem nada para mostrar (sem os dois campos, é `payload_unrecognized`)
falta text ou attachments	`text`, `attachments` ou `blocks` presente, mas sem texto nem `attachments` com `color` (sem nenhum dos três campos, é `payload_unrecognized`)
passa de 2.000 caracteres	`text` grande demais
tem de ter de 1 a 128 caracteres ASCII visíveis, sem espaço	`key` fora do formato

O que fazer: corrija o campo que o message cita.

`rate_limited`

429. Muitos envios seguidos. O corpo traz retry_after (segundos, decimal), e o cabeçalho Retry-After traz o mesmo valor em segundos inteiros, como no Discord.

{
  "code": "rate_limited",
  "message": "Muitos envios seguidos. Espere um pouco e tente de novo.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#rate_limited",
  "retry_after": 0.8
}

O que fazer: espere retry_after segundos e tente de novo. Se a ferramenta dispara muita coisa de uma vez, junte os avisos num cartão só ou use a key (Cartão e key). Os limites estão em Limites.

`internal`

500. Algo deu errado do nosso lado.

{
  "code": "internal",
  "message": "Algo deu errado do nosso lado. Tente de novo.",
  "docs": "https://developers.ggspeak.app/webhooks/erros#internal"
}

O que fazer: tente de novo daqui a pouco. Se continuar, avise a equipe do GGspeak.