Error types

Every RyzeAPI response has a predictable format. Understanding this format is the first step to handling errors robustly in your code.

General response format

All responses begin with the success field, which indicates whether the operation succeeded.

Success
Error

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

Common fields in success responses:

Field	Meaning
`success`	Always `true` on success
`message`	Readable description of what happened (use only for log/UI)
`status`	Business code when applicable (e.g., `sent`, `connected`)
`data`	Useful payload for the endpoint (varies by case)

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

Error response fields:

Field	Meaning
`success`	Always `false` on error
`error.message`	Descriptive text of the problem

The error envelope has only success + error.message. There is no numeric code field nor errorType. Programmatic differentiation must be done by the HTTP status combined with the content of error.message.

HTTP codes

HTTP	Meaning	When it appears
`200`	OK	Successful read/synchronous operation
`201`	Created	Creation
`202`	Accepted	Asynchronous job created
`400`	Bad Request	Body/query validation failed; instance disconnected; invalid identifier
`401`	Unauthorized	Token missing or invalid
`403`	Forbidden	Token valid but no permission (ownership)
`404`	Not Found	Instance/group/resource does not exist
`409`	Conflict	Duplicate instance name; duplicate webhook
`429`	Too Many Requests	Rate limit; WhatsApp throttling
`500`	Internal Server Error	Internal error (DB, encryption, whatsmeow)
`501`	Not Implemented	Operation not supported by the embedded whatsmeow
`503`	Service Unavailable	Chatwoot module not enabled on the server; instance not connected

Literal messages by category

Fine-grained differentiation between errors is done through the text of error.message. Below are the messages you may encounter.

Authentication (401)

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

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

Validation (400)

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

Instance state (400/503)

HTTP	Message
400	`Instance is not connected to WhatsApp`
503	`Instance not connected` (when critical for the operation)

Rate limit (429)

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

Conflict (409)

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

Integrations (Chatwoot)

HTTP	Message	Cause
401	`Chatwoot rejected the API token - verify chatwootApiToken. Detail: ...`	Invalid Chatwoot token
403	`Chatwoot denied the request - verify the API token has admin scope on account <id>. Detail: ...`	Token lacks admin permission
400	`Chatwoot account or endpoint not found - verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...`	Wrong `account_id` or URL
400	`Chatwoot rejected the request as invalid ... Detail: ...`	Chatwoot 422 error
502	`Chatwoot is unreachable at <url> - verify chatwootBaseUrl and that the host is reachable from the server. Detail: ...`	DNS, refused, timeout, or 5xx
503	`integration gateway not configured`	Chatwoot module not enabled on the server

The root cause coming from Chatwoot is always included after Detail: for diagnosis.

Integrations (Typebot)

HTTP	Message	Cause
400	`invalid body: ...`	Malformed body, invalid `typebotUrl`, or `triggerType` outside `all`/`keyword`
400	`triggerOperator and triggerValue are required when triggerType is 'keyword'`	`keyword` trigger without operator/value
400	`this instance already has an enabled 'all' trigger bot`	An enabled `all` bot already exists (uniqueness)
400	`another enabled bot already uses this trigger operator+value`	A `keyword` bot with the same `(operator, value)` already exists
404	`instance not found`	Instance does not exist
404	`bot not found` / `bot not found for this instance`	`botId` does not exist in this instance
404	`no typebot integration for this instance — create a bot first`	`start` with no registered bot
503	`integration gateway not configured`	Ryze Bridge not configured on the server (only in `set` and `start`)

The 503 for Typebot only appears in POST /api/typebot/set/:instance and POST /api/typebot/start/:instance. The list, find, and delete endpoints respond even without the bridge.

Unsupported features (501)

Message
`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: delivery errors

Failed webhooks do not return a synchronous error, they are persisted in a queue with:

status: pending / delivered / failed
attempts, max_attempts (default 5)
last_error: full message
next_retry_at: timestamp of the next retry

Exponential backoff:

Attempt	Next retry
1 (fail)	+1s
2 (fail)	+5s
3 (fail)	+30s
4 (fail)	+5min
5 (fail)	+30min
6+	+1h (cap)

After max_attempts, the status becomes failed and the row remains as a Dead Letter Queue (audit/manual replay). Details in Events.

Best practices

Always check success before assuming the content is valid.

HTTP status is the source of truth, different payloads can have the same error.message.

Retry 429 with exponential backoff; respect the global limit of 100/min.

Do not retry 4xx in general (except 408, 429).

For 503 on Chatwoot, recognize that the Chatwoot module is not enabled on the server and stop retrying, log it for the operator.

Schema validation errors

When you send a body with the wrong format (missing required field, incompatible type, etc.), the API returns 400 with a descriptive text:

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

Do not parse the text finely, validate your body before sending using the schemas documented at each endpoint.

Authentication

Details about tokens and ownership.

Rate limit

Per-minute limits and how to react to 429.

Getting started

Fundamentals

MCP

General response format

HTTP codes

Literal messages by category

Webhooks: delivery errors

Best practices

Schema validation errors

Next

Authentication

Rate limit

​General response format

​HTTP codes

​Literal messages by category

​Webhooks: delivery errors

​Best practices

​Schema validation errors

​Next

Authentication

Rate limit

General response format

HTTP codes

Literal messages by category

Webhooks: delivery errors

Best practices

Schema validation errors

Next