> ## 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.
# Error types
> Response format and HTTP codes the API returns
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.
```json theme={null}
{
"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) |
```json theme={null}
{
"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.
| 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 : ` |
| `invalid group JID : ` |
| `invalid community JID : ` |
| `Invalid action. Must be one of: add, remove, promote, demote, approve, reject` |
| `Invalid 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` |
| HTTP | Message |
| :--: | ---------------------------------------------------------- |
| 400 | `Instance is not connected to WhatsApp` |
| 503 | `Instance 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)` |
| 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 . 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 - 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.
| 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](/en/api/events/overview).
## 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:
```json theme={null}
{
"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
Details about tokens and ownership.
Per-minute limits and how to react to 429.