Error envelope
{
"success": false,
"message": "Invalid webhook url",
"code": "invalid_webhook_url",
"httpCode": 400
}
success luôn là false.code là định danh lỗi ổn định, viết thường — field để branch.httpCode phản ánh HTTP status; transport status cùng giá trị.message là context cho người đọc, có thể đổi giữa các release.
Lỗi xác thực và scope
| HTTP | code | Ý nghĩa |
|---|
| 401 | unauthorized | Sai hoặc thiếu header access-key. |
| 401 | unauthorized ("missing access keys") | Thiếu một trong hai header. |
| 401 | unauthorized ("missing user id") | Endpoint theo user được gọi thiếu userId. |
| 401 | unauthorized ("Partner user not found") | userId chưa đăng ký dưới partner của bạn. |
| 401 | unauthorized ("partner api key is disabled") | API key tồn tại nhưng đang bị tắt — liên hệ Zenith. |
| 403 | "partner type not allowed to call this API" | Loại partner của bạn không được dùng endpoint này. |
| 403 | "missing required api scope: <scope>" | Endpoint cần scope mà key không có. |
| 403 | KYC gate | Endpoint virtual-account: KYC của user chưa approved. |
| 429 | too_many_requests | >10 lần auth sai trong 60s, hoặc chạm rate limit của endpoint. |
Các domain code thường gặp
| code | Ở đâu | Ý nghĩa |
|---|
invalid_webhook_url | update-webhook | URL không phải HTTPS hoặc không thuộc domain đã đăng ký. |
invalid_email_format | create user | Email không hợp lệ. |
amount_to_low / amount_to_high | transfers | Số tiền ngoài dải cho phép. |
concurrency_issue_detected | nhiều nơi | Ghi đồng thời xung đột — retry với backoff. |
internal_server_error | bất kỳ | Lỗi bất ngờ — retry; liên hệ Zenith nếu lặp lại. |
Hướng xử lý
- Retry idempotent với
5xx và concurrency_issue_detected, backoff lũy tiến. - Không retry
4xx nếu không sửa request. - Log cả
code + message — message mang context Zenith cần khi bạn escalate.
