Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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. 
{
  "success": true,
  "message": "Message sent successfully",
  "status": "sent",
  "data": { "...": "..." }
}
Campos comuns em respostas de sucesso:
CampoSignificado
successSempre true em sucesso
messageDescrição legível do que aconteceu (use só para log/UI)
statusCódigo de negócio quando aplicável (ex.: sent, connected)
dataPayload útil do endpoint (varia conforme o caso)
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

HTTPSignificadoQuando aparece
200OKSucesso de leitura/operação síncrona
201CreatedCriação
202AcceptedJob assíncrono criado
400Bad RequestValidação de body/query falhou; instância desconectada; identificador inválido
401UnauthorizedToken ausente ou inválido
403ForbiddenToken válido mas sem permissão (ownership)
404Not FoundInstância/grupo/recurso não existe
409ConflictNome duplicado de instância; webhook duplicado
429Too Many RequestsRate limit; throttling do WhatsApp
500Internal Server ErrorErro interno (DB, encryption, whatsmeow)
501Not ImplementedOperação não suportada pelo whatsmeow embarcado
503Service UnavailableBridge (RyzeIntegrations) não configurado; 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.
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
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
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
HTTPMensagem
400Instance is not connected to WhatsApp
503Instance not connected (quando crítica para a operação)
Mensagem
Rate limit exceeded
rate limit exceeded (429): wait before creating again (throttling do WhatsApp)
Mensagem
Instance with this name already exists
webhook limit reached (max 3 enabled per instance)
HTTPMensagemCausa
401Chatwoot rejected the API token — verify chatwootApiToken. Detail: ...Token Chatwoot inválido
403Chatwoot denied the request — verify the API token has admin scope on account <id>. Detail: ...Token sem permissão de admin
400Chatwoot account or endpoint not found — verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...account_id ou URL incorretos
400Chatwoot rejected the request as invalid ... Detail: ...Erro 422 do Chatwoot
502Chatwoot is unreachable at <url> — verify chatwootBaseUrl and that the host is reachable from the server. Detail: ...DNS, refused, timeout, ou 5xx
503integration gateway not configured (set BRIDGE_URL and BRIDGE_TOKEN)Bridge desligado no servidor
A causa-raiz vinda do Chatwoot/bridge é incluída sempre após Detail: para diagnóstico.
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:
TentativaPró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, descubra que o bridge não está ativo 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.

​
Próximo

Autenticação

Detalhes sobre tokens e ownership.

Rate limit

Limites por minuto e como reagir ao 429.