Lỗi và giới hạn
Xử lý API errors, idempotency, rate limits và WebSocket close codes.
HTTP và SSE errors
Mọi lỗi /v1, kể cả lỗi xác thực và validation, dùng cấu trúc ổn định sau.
{
"code": "RATE_LIMITED",
"message": "Request rate limit exceeded",
"details": null,
"request_id": "req_01K...",
"retryable": true
}Trong SSE, cùng dữ liệu được gửi trong terminal event error. Luôn lưu request_id để hỗ trợ điều tra.
| Code | HTTP thường gặp | Retry? | Cách xử lý |
|---|---|---|---|
INVALID_API_KEY | 401 | Không | Kiểm tra key, checksum và Authorization header. Key đã xóa cũng trả mã này. |
API_KEY_EXPIRED | 401 | Không | Key hết hạn hoặc hết thời gian ân hạn khi rotate; dùng key thay thế. |
API_KEY_REVOKED | 401 | Không | Dùng credential đang hoạt động. |
INSUFFICIENT_SCOPE | 403 | Không | Tạo key với scope cần thiết. |
IP_NOT_ALLOWED | 403 | Không | Gọi từ IP nằm trong allowlist của key. |
ASSISTANT_INACTIVE | 403 | Không | Kích hoạt lại trợ lý. |
FEATURE_NOT_AVAILABLE | 403 | Không | Kiểm tra plan, feature của owner và model yêu cầu. |
FILE_UPLOAD_DISABLED | 403 | Không | Bật upload tệp cho trợ lý. |
VOICE_DISABLED | 403 | Không | Bật giọng nói cho trợ lý. |
ACTOR_CONFLICT | 409 | Không | Dùng external_user_id khác. |
INSUFFICIENT_CREDITS | 429 | Không ngay | Owner cần bổ sung credits. |
RATE_LIMITED | 429 | Có | Chờ Retry-After. |
IDEMPOTENCY_CONFLICT | 409 | Không | Dùng key mới hoặc body ban đầu. |
REQUEST_IN_PROGRESS | 409 | Có | Chờ rồi retry cùng key/body. |
CONVERSATION_NOT_FOUND | 404 | Không | Kiểm tra assistant, external user và UUID. |
MESSAGE_NOT_FOUND | 404 | Không | Kiểm tra message ID và external user. |
FILE_NOT_FOUND | 404 | Không | Upload tệp cho cùng external user; details.file_id chỉ rõ tệp. |
RESPONSE_NOT_FOUND | 404 | Không | Kiểm tra ID và external user; thử lại sau khi response hoàn tất. |
INVALID_CURSOR | 400 | Không | Truyền last_id của cùng hội thoại vào after. |
VALIDATION_ERROR | 422 | Không | Sửa request; details.errors liệt kê field lỗi. |
UNSUPPORTED_FILE_TYPE | 415 | Không | Tải lên loại file được hỗ trợ, có nội dung khớp với phần mở rộng. |
FILE_TOO_LARGE | 413 | Không | Upload tệp tối đa 25 MiB. |
INVALID_AUDIO_FORMAT | 400 | Không | Dùng codec/rate/channel được hỗ trợ. |
CONTEXT_TOO_LARGE | 400 | Không | Tạo hội thoại mới. |
UPSTREAM_UNAVAILABLE | 503 | Có | Backoff và retry có giới hạn. |
RATE_LIMIT_UNAVAILABLE | 503 | Có | Backoff và retry; API fail closed. |
INTERNAL_SERVER_ERROR | 500 | Có | Retry có backoff và gửi request_id cho support. |
Chỉ retry khi retryable là true hoặc tài liệu chỉ rõ. Dùng exponential backoff có jitter, đặt số lần thử tối đa và giữ cùng idempotency key cho cùng thao tác logic.
Rate limits
Response có thể chứa:
| Header | Ý nghĩa |
|---|---|
RateLimit-Limit | Số request tối đa trong window hiện tại. |
RateLimit-Remaining | Số request còn lại. |
RateLimit-Reset | Số giây đến khi window hiện tại reset. |
Retry-After | Số giây phải chờ sau lỗi 429. |
X-Request-ID | ID dùng để trace/support. |
Giới hạn dùng chung cho mọi key của một trợ lý, nên tạo thêm key không tăng hạn mức. Giới hạn mặc định:
| Bucket | Giới hạn |
|---|---|
| Tất cả API requests | 120/phút |
| Chat responses | 30/phút |
| Tạo voice session | 20/phút |
Plan Enterprise cho phép 600 requests, 120 chat responses và 60 voice sessions mỗi phút. Giới hạn dùng sliding window một phút. Client nên đọc headers thay vì hard-code các giá trị này.
WebSocket errors
{
"type": "error",
"sequence": 8,
"error": {
"code": "INVALID_EVENT_ORDER",
"message": "Audio frames require input_audio.start",
"retryable": false
}
}Close codes:
| Code | Ý nghĩa |
|---|---|
1000 | Kết thúc bình thường. |
1002 | Protocol violation. |
1008 | Authentication, policy, ordering hoặc limit violation. |
1009 | JSON/binary frame quá lớn. |
1011 | Lỗi provider hoặc lỗi server. |
Không reconnect với cùng session token. Với lỗi có thể retry, yêu cầu backend cấp token mới rồi mở connection mới. Với 1008, sửa credential, origin, event order hoặc limit trước khi thử lại.
Khi liên hệ support
Gửi endpoint, timestamp, HTTP status/close code, request_id, session_id và public credential prefix. Không gửi full API key, session token, raw audio hoặc dữ liệu cá nhân không cần thiết.