API errors and limits
Handle validation, authentication, permissions, quotas and rate limits.
Recognize the response
Successful JSON operations return a data field. Chat returns an SSE stream. Most application errors include an error string and may add code, message or context. Validation errors can use a success: false response with a structured error object. Read the status and body together.
| Status | Typical cause | Action |
|---|---|---|
| 400 | Invalid input, missing enterprise tier or missing reschedule slot. | Correct the fields and retry. |
| 401 | Missing, invalid, expired or revoked token. | Use a valid token from the correct workspace/environment. |
| 402 | api_locked, unavailable live access or exhausted purchase/quota capacity. | Review Billing, plan eligibility and Usage. |
| 403 | Missing scope, disallowed bot or unavailable enterprise tier capacity. | Use the correct permission/bot or resolve the tier capacity. |
| 404 | Record or account not found in the accessible context. | Check the ID and workspace. |
| 409 | Duplicate bot name or booking conflict/state already changed. | Read the returned code and current resource state before retrying. |
| 429 | Request rate exceeded. | Wait for Retry-After seconds and use backoff. |
Request and list limits
- Bot names: 1–30 characters; use a unique name in the workspace.
- Knowledge title: 1–300 characters; provide a URL or nonempty text. Text is limited to 200,000 characters.
- Chat message: 1–2,000 characters. sessionId can be at most 120 characters.
- Conversation search q: at most 200 characters; list limit is 1–200, default 50.
- Booking list limit: 1–200, default 200. Leads return at most 500 newest records.
- These bounded lists do not provide a page/cursor parameter. Billing history pagination is a separate dashboard feature.
- Per-token rate limits follow the plan: Growth 120/minute, Scale 300/minute. Enterprise follows the contract rate-limiting setting.
Retry without duplicating work
Retry read requests after a transient network failure with backoff. For writes, inspect the result/current state before repeating a request whose outcome is unknown. The regular workspace API does not promise the Vendor API’s idempotency contract. A booking update can send a visitor email and must be treated as an action, not a harmless read.
- A bot-name conflict can include a suggested_name; it does not mean the original request failed before creating anything.
- Use requestedSlot with an explicit timezone offset for rescheduling.
- Confirm/reject apply to pending bookings. Reschedule/cancel apply to pending or confirmed bookings.
- Do not retry unchanged 401/402/403 responses repeatedly. Resolve their underlying cause.