Tipos de error

Cada respuesta de RyzeAPI tiene un formato predecible. Comprender este formato es el primer paso para manejar errores de manera robusta en tu código.

Formato general de respuesta

Todas las respuestas comienzan con el campo success, que indica si la operación fue exitosa.

Éxito
Error

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

Campos comunes en respuestas exitosas:

Campo	Significado
`success`	Siempre `true` en éxito
`message`	Descripción legible de lo que ocurrió (úsalo solo para log/UI)
`status`	Código de negocio cuando aplica (por ejemplo, `sent`, `connected`)
`data`	Payload útil del endpoint (varía según el caso)

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

Campos en respuestas de error:

Campo	Significado
`success`	Siempre `false` en error
`error.message`	Texto descriptivo del problema

El envoltorio de error tiene solo success + error.message. No hay un campo numérico code ni errorType. La diferenciación programática debe hacerse mediante el status HTTP combinado con el contenido de error.message.

Códigos HTTP

HTTP	Significado	Cuándo aparece
`200`	OK	Operación exitosa de lectura/síncrona
`201`	Created	Creación
`202`	Accepted	Trabajo asíncrono creado
`400`	Bad Request	Falla de validación de body/query; instancia desconectada; identificador inválido
`401`	Unauthorized	Token ausente o inválido
`403`	Forbidden	Token válido pero sin permiso (ownership)
`404`	Not Found	Instancia/grupo/recurso no existe
`409`	Conflict	Nombre de instancia duplicado; webhook duplicado
`429`	Too Many Requests	Límite de velocidad; throttling de WhatsApp
`500`	Internal Server Error	Error interno (DB, cifrado, whatsmeow)
`501`	Not Implemented	Operación no soportada por el whatsmeow embebido
`503`	Service Unavailable	Módulo Chatwoot no habilitado en el servidor; instancia no conectada

Mensajes literales por categoría

La diferenciación granular entre errores se hace a través del texto de error.message. A continuación, los mensajes que puedes encontrar.

Autenticación (401)

Mensaje
`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)

Mensaje
`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`

Validación (400)

Mensaje
`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 de la instancia (400/503)

HTTP	Mensaje
400	`Instance is not connected to WhatsApp`
503	`Instance not connected` (cuando es crítico para la operación)

Límite de velocidad (429)

Mensaje
`Rate limit exceeded`
`rate limit exceeded (429): wait before creating again` (throttling de WhatsApp)

Conflicto (409)

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

Integraciones (Chatwoot)

HTTP	Mensaje	Causa
401	`Chatwoot rejected the API token - verify chatwootApiToken. Detail: ...`	Token de Chatwoot inválido
403	`Chatwoot denied the request - verify the API token has admin scope on account <id>. Detail: ...`	El token carece de permiso de admin
400	`Chatwoot account or endpoint not found - verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...`	`account_id` o URL incorrectos
400	`Chatwoot rejected the request as invalid ... Detail: ...`	Error 422 de Chatwoot
502	`Chatwoot is unreachable at <url> - verify chatwootBaseUrl and that the host is reachable from the server. Detail: ...`	DNS, conexión rechazada, timeout o 5xx
503	`integration gateway not configured`	Módulo Chatwoot no habilitado en el servidor

La causa raíz proveniente de Chatwoot siempre se incluye después de Detail: para diagnóstico.

Integraciones (Typebot)

HTTP	Mensaje	Causa
400	`invalid body: ...`	Body malformado, `typebotUrl` inválida o `triggerType` fuera de `all`/`keyword`
400	`triggerOperator and triggerValue are required when triggerType is 'keyword'`	Trigger `keyword` sin operador/valor
400	`this instance already has an enabled 'all' trigger bot`	Ya existe un bot `all` habilitado (unicidad)
400	`another enabled bot already uses this trigger operator+value`	Ya existe un bot `keyword` con el mismo `(operator, value)`
404	`instance not found`	La instancia no existe
404	`bot not found` / `bot not found for this instance`	El `botId` no existe en esta instancia
404	`no typebot integration for this instance — create a bot first`	`start` sin ningún bot registrado
503	`integration gateway not configured`	Ryze Bridge no configurado en el servidor (solo en `set` y `start`)

El 503 de Typebot solo aparece en POST /api/typebot/set/:instance y POST /api/typebot/start/:instance. Los endpoints list, find y delete responden incluso sin el bridge.

Funciones no soportadas (501)

Mensaje
`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: errores de entrega

Los webhooks fallidos no devuelven un error síncrono, se persisten en una cola con:

status: pending / delivered / failed
attempts, max_attempts (predeterminado 5)
last_error: mensaje completo
next_retry_at: timestamp del próximo reintento

Backoff exponencial:

Intento	Próximo reintento
1 (falla)	+1s
2 (falla)	+5s
3 (falla)	+30s
4 (falla)	+5min
5 (falla)	+30min
6+	+1h (cap)

Después de max_attempts, el estado pasa a failed y la fila permanece como Dead Letter Queue (auditoría/replay manual). Detalles en Eventos.

Buenas prácticas

Siempre verifica success antes de asumir que el contenido es válido.

El status HTTP es la fuente de verdad, payloads diferentes pueden tener el mismo error.message.

Reintenta 429 con backoff exponencial; respeta el límite global de 100/min.

No reintentes 4xx en general (excepto 408, 429).

Para 503 en Chatwoot, reconoce que el módulo Chatwoot no está habilitado en el servidor y deja de reintentar, regístralo para el operador.

Errores de validación de schema

Cuando envías un body con formato incorrecto (campo requerido faltante, tipo incompatible, etc.), la API devuelve 400 con un texto descriptivo:

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

No analices el texto de forma fina, valida tu body antes de enviarlo usando los schemas documentados en cada endpoint.

Autenticación

Detalles sobre tokens y ownership.

Límite de velocidad

Límites por minuto y cómo reaccionar a 429.

Primeros pasos

Fundamentos

MCP

Formato general de respuesta

Códigos HTTP

Mensajes literales por categoría

Webhooks: errores de entrega

Buenas prácticas

Errores de validación de schema

Siguiente

Autenticación

Límite de velocidad

​Formato general de respuesta

​Códigos HTTP

​Mensajes literales por categoría

​Webhooks: errores de entrega

​Buenas prácticas

​Errores de validación de schema

​Siguiente

Autenticación

Límite de velocidad

Formato general de respuesta

Códigos HTTP

Mensajes literales por categoría

Webhooks: errores de entrega

Buenas prácticas

Errores de validación de schema

Siguiente