Skip to main content

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.

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": true,
  "message": "Message sent successfully",
  "status": "sent",
  "data": { "...": "..." }
}
Common fields in success responses:
FieldMeaning
successAlways true on success
messageReadable description of what happened (use only for log/UI)
statusBusiness code when applicable (e.g., sent, connected)
dataUseful payload for the endpoint (varies by case)
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

HTTPMeaningWhen it appears
200OKSuccessful read/synchronous operation
201CreatedCreation
202AcceptedAsynchronous job created
400Bad RequestBody/query validation failed; instance disconnected; invalid identifier
401UnauthorizedToken missing or invalid
403ForbiddenToken valid but no permission (ownership)
404Not FoundInstance/group/resource does not exist
409ConflictDuplicate instance name; duplicate webhook
429Too Many RequestsRate limit; WhatsApp throttling
500Internal Server ErrorInternal error (DB, encryption, whatsmeow)
501Not ImplementedOperation not supported by the embedded whatsmeow
503Service UnavailableBridge (RyzeIntegrations) not configured; 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.
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
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
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
HTTPMessage
400Instance is not connected to WhatsApp
503Instance not connected (when critical for the operation)
Message
Rate limit exceeded
rate limit exceeded (429): wait before creating again (WhatsApp throttling)
Message
Instance with this name already exists
webhook limit reached (max 3 enabled per instance)
HTTPMessageCause
401Chatwoot rejected the API token — verify chatwootApiToken. Detail: ...Invalid Chatwoot token
403Chatwoot denied the request — verify the API token has admin scope on account <id>. Detail: ...Token lacks admin permission
400Chatwoot account or endpoint not found — verify chatwootBaseUrl (...) and chatwootAccountId (...). Detail: ...Wrong account_id or URL
400Chatwoot rejected the request as invalid ... Detail: ...Chatwoot 422 error
502Chatwoot is unreachable at <url> — verify chatwootBaseUrl and that the host is reachable from the server. Detail: ...DNS, refused, timeout, or 5xx
503integration gateway not configured (set BRIDGE_URL and BRIDGE_TOKEN)Bridge disabled on the server
The root cause coming from Chatwoot/bridge is always included after Detail: for diagnosis.
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:
AttemptNext 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 bridge is not active 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.

​
Next

Authentication

Details about tokens and ownership.

Rate limit

Per-minute limits and how to react to 429.