Troubleshooting
Common Errors
Catalog of top Asiyst error codes, root causes, diagnostic HTTP headers, and verified fixes.
Overview
This reference compiles the most frequent errors encountered across the SDK, CLI, and REST API, along with immediate remediation steps.
Error Code Catalog
| Error Code | HTTP Status | Root Cause | Immediate Fix |
|---|---|---|---|
DOMAIN_NOT_ALLOWED | 403 | Origin header is not on the Allowed Domains list | Add domain to Project Settings > Allowed Domains |
INVALID_CREDENTIALS | 401 | Public key or API token is missing or mistyped | Verify pk_live_ key in project settings |
RATE_LIMIT_EXCEEDED | 429 | Exceeded requests per minute quota | Implement exponential backoff or upgrade plan |
KNOWLEDGE_EMPTY | 400 | No indexed sources linked to assistant | Connect and index at least one source |
AVATAR_UNPUBLISHED | 404 | Selected avatar model was deleted or unassigned | Re-assign avatar in Avatar Studio |
SESSION_EXPIRED | 401 | Visitor token has surpassed maximum TTL (24 hours) | SDK automatically re-handshakes on next message |
Resolution Playbooks
1. DOMAIN_NOT_ALLOWED
[Asiyst] 403: Origin 'https://sub.myco.com' is not permitted.- Open dashboard -> Connect Site -> Allowed Domains.
- Add
https://sub.myco.com.
- Save and reload your page.
2. RATE_LIMIT_EXCEEDED
[Asiyst] 429: Too many requests. Retry after 10s.- Check the
retry-afterHTTP header.
- Reduce frequency of automated polling or batch calls.
Reporting Unresolved Bugs
If an issue persists after reviewing these guides:
- Run
asiyst diagnostics --output diagnostics.json.
- Open a ticket at Asiyst Support Portal or reach out on our developer Discord.