Hướng dẫn

Mã lỗi

Mọi lỗi trả về cùng một envelope. Dùng error.code để xử lý logic và requestId để đối soát log.

Error envelope

json

{
  "error": {
    "code": "CONFLICT",
    "message": "Device already has an eSIM assigned",
    "details": { "deviceId": "meter-hn-014" },
    "requestId": "2f2ffb6a-…"
  }
}

HTTP	Code	Xử lý
400	VALIDATION_ERROR	Payload/query sai định dạng. Kiểm tra details.path.
401	UNAUTHORIZED	Thiếu hoặc sai x-api-key/session.
403	ACCOUNT_PENDING	Tài khoản chưa được kích hoạt.
403	FORBIDDEN	Không có quyền với tài nguyên.
404	NOT_FOUND	ICCID/job không tồn tại hoặc thuộc partner khác.
409	CONFLICT	Trạng thái không hợp lệ, device đã gán eSIM, hoặc job khác đang chạy.
422	UNPROCESSABLE_ENTITY	Dữ liệu đúng định dạng nhưng không xử lý được.
429	RATE_LIMITED	Vượt rate limit; backoff theo Retry-After.
502	TELCO_ERROR	Viettel trả lỗi hoặc không phản hồi sau retry.
503	SERVICE_UNAVAILABLE	Queue/hạ tầng tạm thời không sẵn sàng.
500	INTERNAL_ERROR	Lỗi không mong đợi; gửi requestId cho KOVITEL.

Retry

Retry được: 429, 502, 503, timeout mạng.
Không retry: 400, 401, 403, 404, 409, 422.
Dùng exponential backoff + jitter; tôn trọng header Retry-After nếu có.
Với job bất đồng bộ, retry an toàn bằng cách poll job hiện tại thay vì tạo request mới.

Khi cần hỗ trợ

Gửi requestId, thời điểm, endpoint và payload (che key) tới admin@kovitel.com. KOVITEL đối soát log theo requestId.