Tipos de erro

Toda resposta da RyzeAPI tem um formato previsível. Entender esse formato é o primeiro passo para tratar erros com robustez no seu código.

Formato geral das respostas

Todas começam com o campo success, que indica se a operação deu certo.

Sucesso
Erro

{
  "success": true,
  "message": "Message sent successfully",
  "status": "sent",
  "data": { "...": "..." }
}

Campos comuns em respostas de sucesso:

Campo	Significado
`success`	Sempre `true` em sucesso
`message`	Descrição legível do que aconteceu (use só para log/UI)
`status`	Código de negócio quando aplicável (ex.: `sent`, `connected`)
`data`	Payload útil do endpoint (varia conforme o caso)

{
  "success": false,
  "error": {
    "message": "Instance is not connected to WhatsApp"
  }
}

Campos da resposta de erro:

Campo	Significado
`success`	Sempre `false` em erro
`error.message`	Texto descritivo do problema

O envelope de erro tem apenas success + error.message. Não existe campo code numérico nem errorType. A diferenciação programática deve ser feita pelo status HTTP combinado com o conteúdo de error.message.

Códigos HTTP

HTTP	Significado	Quando aparece
`200`	OK	Sucesso de leitura/operação síncrona
`201`	Created	Criação
`202`	Accepted	Job assíncrono criado
`400`	Bad Request	Validação de body/query falhou; instância desconectada; identificador inválido
`401`	Unauthorized	Token ausente ou inválido
`403`	Forbidden	Token válido mas sem permissão (ownership)
`404`	Not Found	Instância/grupo/recurso não existe
`409`	Conflict	Nome duplicado de instância; webhook duplicado
`429`	Too Many Requests	Rate limit; throttling do WhatsApp
`500`	Internal Server Error	Erro interno (DB, encryption, whatsmeow)
`501`	Not Implemented	Operação não suportada pelo whatsmeow embarcado
`503`	Service Unavailable	Módulo Chatwoot não habilitado no servidor; instância não conectada

Mensagens literais por categoria

A diferenciação fina entre erros é feita pelo texto de error.message. Abaixo, as mensagens que você pode encontrar.

Autenticação (401)

Mensagem
`Missing token in header`
`Missing token in header, Authorization header, or query parameter`
`Missing token`
`Invalid token`
`Invalid instance token`
`Invalid account token`
`Unauthenticated`

Ownership (403)

Mensagem
`Instance token does not match requested instance`
`Instance does not belong to this account`
`Not authorized to view group requests (must be admin)`
`Not authorized to perform this action (must be admin)`
`Not authorized to update this group (must be admin)`
`Not authorized to reset group invite link (must be admin)`
`Not allowed to join this group`
`Not allowed to leave this group`

Validação (400)

Mensagem
`Instance name is required`
`Invalid request body`
`The 'name' field is required`
`The 'identifier' query parameter is required (...)`
`At least one participant is required`
`At least one field must be provided ...`
`At least one privacy setting must be provided`
`group name must be 25 characters or less`
`Community name must be 25 characters or less`
`invalid participant <number>: <reason>`
`invalid group JID <jid>: <reason>`
`invalid community JID <jid>: <reason>`
`Invalid action. Must be one of: add, remove, promote, demote, approve, reject`
`Invalid <field> value: <value>. Valid values: ...`
`Invalid duration format`
`Invalid invite link or code`
`Invite link has been revoked or expired`
`Number not found or not registered on WhatsApp`
`invalid LID format`

Estado da instância (400/503)

HTTP	Mensagem
400	`Instance is not connected to WhatsApp`
503	`Instance not connected` (quando crítica para a operação)

Rate limit (429)

Mensagem
`Rate limit exceeded`
`rate limit exceeded (429): wait before creating again` (throttling do WhatsApp)

Conflito (409)

Mensagem
`Instance with this name already exists`
`webhook limit reached (max 3 enabled per instance)`

Integrações (Chatwoot)

HTTP	Mensagem	Causa
401	`Chatwoot rejected the API token - verify chatwootApiToken. Detail: ...`	Token Chatwoot inválido
403	`Chatwoot denied the request - verify the API token has admin scope on account <id>. Detail: ...`	Token sem permissão de admin
400	`Chatwoot account or endpoint not found - verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...`	`account_id` ou URL incorretos
400	`Chatwoot rejected the request as invalid ... Detail: ...`	Erro 422 do Chatwoot
502	`Chatwoot is unreachable at <url> - verify chatwootBaseUrl and that the host is reachable from the server. Detail: ...`	DNS, refused, timeout, ou 5xx
503	`integration gateway not configured`	Módulo Chatwoot não habilitado no servidor

A causa-raiz vinda do Chatwoot é incluída sempre após Detail: para diagnóstico.

Integrações (Typebot)

HTTP	Mensagem	Causa
400	`invalid body: ...`	Body malformado, `typebotUrl` inválida ou `triggerType` fora de `all`/`keyword`
400	`triggerOperator and triggerValue are required when triggerType is 'keyword'`	Trigger `keyword` sem operador/valor
400	`this instance already has an enabled 'all' trigger bot`	Já existe um bot `all` habilitado (unicidade)
400	`another enabled bot already uses this trigger operator+value`	Já existe um bot `keyword` com o mesmo `(operator, value)`
404	`instance not found`	Instância não existe
404	`bot not found` / `bot not found for this instance`	`botId` não existe nesta instância
404	`no typebot integration for this instance — create a bot first`	`start` sem nenhum bot cadastrado
503	`integration gateway not configured`	Ryze Bridge não configurado no servidor (só em `set` e `start`)

O 503 do Typebot só aparece em POST /api/typebot/set/:instance e POST /api/typebot/start/:instance. Os endpoints list, find e delete respondem mesmo sem o bridge.

Recursos não suportados (501)

Mensagem
`WhatsApp client does not support newsletter creation (CreateNewsletter not available)`
`WhatsApp client does not support listing newsletters (GetSubscribedNewsletters not available)`
`WhatsApp client does not support GetNewsletterInfo`
`WhatsApp client does not support GetNewsletterInfoWithInvite`
`WhatsApp client does not support FollowNewsletter`
`WhatsApp client does not support UnfollowNewsletter`

Webhooks: erros de entrega

Webhooks falhos não retornam erro síncrono, são persistidos numa fila com:

status: pending / delivered / failed
attempts, max_attempts (default 5)
last_error: mensagem completa
next_retry_at: timestamp do próximo retry

Backoff exponencial:

Tentativa	Próximo retry
1 (fail)	+1s
2 (fail)	+5s
3 (fail)	+30s
4 (fail)	+5min
5 (fail)	+30min
6+	+1h (cap)

Após max_attempts, status vira failed e a row permanece como Dead Letter Queue (auditoria/manual replay). Detalhes em Eventos.

Boas práticas

Sempre cheque success antes de assumir que o conteúdo é válido.

Status HTTP é fonte de verdade, diferentes payloads podem ter o mesmo error.message.

Retentar 429 com backoff exponencial; respeite o limite global de 100/min.

Não retentar 4xx em geral (exceto 408, 429).

Para 503 no Chatwoot, entenda que o módulo Chatwoot não está habilitado no servidor e pare tentativas, logue para o operador.

Erros de validação de schema

Quando você manda um body com formato errado (falta campo obrigatório, tipo incompatível, etc.), a API retorna 400 com texto descritivo:

{
  "success": false,
  "error": {
    "message": "Invalid request body"
  }
}

Não faça parsing fino do texto, valide seu body antes de enviar usando os schemas documentados em cada endpoint.

Autenticação

Detalhes sobre tokens e ownership.

Rate limit

Limites por minuto e como reagir ao 429.

Primeiros passos

Fundamentos

MCP

Formato geral das respostas

Códigos HTTP

Mensagens literais por categoria

Webhooks: erros de entrega

Boas práticas

Erros de validação de schema

Próximo

Autenticação

Rate limit

​Formato geral das respostas

​Códigos HTTP

​Mensagens literais por categoria

​Webhooks: erros de entrega

​Boas práticas

​Erros de validação de schema

​Próximo

Autenticação

Rate limit

Formato geral das respostas

Códigos HTTP

Mensagens literais por categoria

Webhooks: erros de entrega

Boas práticas

Erros de validação de schema

Próximo