API reference
Limits and errors
Handle usage limits and failed requests.
ChatKazi keeps API keys, sessions, usage, and limits scoped to your account.
API hit limits
Every authenticated API request counts toward your monthly API hit limit.
When the limit is reached, ChatKazi returns:
402 Response
{
"error": "Payment Required",
"message": "Monthly API hit limit reached. Upgrade your plan to continue.",
"usage": {
"current": 1000,
"limit": 1000
}
}
Instance limits
Each plan controls how many WhatsApp sessions you can connect.
If you reach your instance limit, session creation fails with a clear upgrade message.
Message failures
Message failures are recorded in usage logs. Common causes include:
- Session is not connected.
- Recipient number is invalid.
- Your account has reached plan limits.
- Media URL is not publicly reachable.
- WhatsApp rejected the send.
Safe retry behavior
Retry only after checking the error type.
| Error | Retry? | Notes |
|---|---|---|
| Missing API key | No | Fix authentication first. |
| Plan limit reached | No | Upgrade or wait for reset. |
| Session disconnected | No | Reconnect the WhatsApp session. |
| Temporary server error | Yes | Retry with backoff. |
Recommended logging
Log these fields in your own backend:
- Request endpoint
sessionId- Recipient phone number
- ChatKazi response status
- ChatKazi response message
- Your customer, order, or workflow reference
Do not log full API keys or sensitive customer message bodies unless your own compliance policy allows it.