Định dạng phản hồi và xử lý lỗi
Cấu trúc JSON mà API iNET trả về khi thành công và khi lỗi, kèm cách xử lý từng mã HTTP.
API của iNET trả về JSON. Khi thành công, kết quả nằm trong trường data. Khi lỗi, success bằng false và trường error cho biết lý do.
Response thành công
{
"success": true,
"data": {
"domainName": "inet.vn",
"available": "unavailable"
},
"meta": {
"request_id": "9b2c1f4e-7a3d-4c51-8e0f-2d6a5b1c3e7f",
"latency_ms": 245,
"endpoint": "/v1/domain/check",
"timestamp": "2026-03-31T08:00:00.000Z"
}
}
| Trường | Kiểu | Mô tả |
|---|---|---|
success | boolean | true khi gọi thành công |
data | object/array | Kết quả trả về |
meta | object | Thông tin về lần gọi |
Các trường trong meta:
| Trường | Kiểu | Mô tả |
|---|---|---|
request_id | string | Mã riêng của lần gọi, gửi kèm khi cần hỗ trợ |
latency_ms | number | Thời gian xử lý (mili giây) |
endpoint | string | Đường dẫn đã gọi |
timestamp | string | Thời điểm xử lý (ISO 8601) |
Response lỗi
Mọi lỗi đều có success: false và trường error là một câu mô tả lỗi. Có hai dạng.
Yêu cầu bị từ chối ngay (API key sai, thiếu quyền, vượt giới hạn, tham số không hợp lệ): phản hồi chỉ gồm success và error.
{
"success": false,
"error": "API key không hợp lệ hoặc chưa được cung cấp"
}
Lỗi trong lúc xử lý yêu cầu: data chứa chi tiết lỗi (khác nhau theo từng API), error nhắc lại thông báo trong đó, meta giống khi thành công.
{
"success": false,
"data": {
"status": "error",
"message": "Tên miền không hợp lệ"
},
"error": "Tên miền không hợp lệ",
"meta": {
"request_id": "4e1a7c2b-0f3d-4b8e-9a6c-1d2e3f4a5b6c",
"latency_ms": 120,
"endpoint": "/v1/domain/check",
"timestamp": "2026-03-31T08:00:01.000Z"
}
}
Lưu ý: error là câu chữ để hiển thị hoặc ghi log, không phải mã lỗi, và nội dung có thể thay đổi. Phân loại lỗi theo mã HTTP ở bảng dưới.
Mã HTTP và cách xử lý
| Mã HTTP | Ý nghĩa | Cách xử lý |
|---|---|---|
| 200 | Thành công | Đọc kết quả trong data |
| 400 | Tham số hoặc đường dẫn không hợp lệ, thiếu trường bắt buộc, hoặc yêu cầu bị từ chối khi xử lý | Sửa tham số theo nội dung error |
| 401 | API key thiếu, sai, đã hết hạn hoặc đã bị thu hồi; hoặc tài khoản đang bị khoá | Kiểm tra lại key; key hết hạn hoặc đã thu hồi thì tạo key mới |
| 403 | API key bị chặn, không có quyền với API này, gọi từ IP không được phép, hoặc gọi API đại lý bằng key không phải ngữ cảnh đại lý | Kiểm tra quyền và danh sách IP của key; key bị chặn thì liên hệ hỗ trợ |
| 404 | API không tồn tại | Kiểm tra đường dẫn trong Tra cứu API |
| 409 | Tài nguyên đã tồn tại, ví dụ tên miền đã có trên tài khoản | Dùng tài nguyên đã có, không tạo lại |
| 429 | Vượt giới hạn truy cập | Chờ số giây trong header Retry-After rồi gọi lại, xem Giới hạn truy cập |
| 500, 502, 503 | Hệ thống đang gặp sự cố hoặc tạm thời không phản hồi | Thử lại sau vài giây |
| 504 | Yêu cầu xử lý quá lâu | Thử lại sau; lặp lại nhiều lần thì liên hệ hỗ trợ kèm request_id |
Ví dụ đọc kết quả và xử lý lỗi
RESPONSE=$(curl -s -w "\n%{http_code}" \
-H "Authorization: Bearer inet_sk_your_api_key" \
"https://developers.inet.vn/api/gateway/v1/domain/check?name=mysite.vn")
STATUS=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')
if [ "$(echo "$BODY" | jq -r '.success')" = "true" ]; then
echo "$BODY" | jq -r '.data.available'
else
echo "Lỗi $STATUS: $(echo "$BODY" | jq -r '.error')"
fiLưu ý khi xử lý lỗi
- Kiểm tra
successtrước: chỉ đọcdatakhisuccesslàtrue. - Phân loại theo mã HTTP: không so khớp nội dung
errortrong code vì câu chữ có thể đổi. - Ghi log
errorvàmeta.request_id: gửirequest_idkhi cần hỗ trợ (lỗi bị từ chối ngay không cómeta). - Lỗi 5xx: thử lại sau 1–2 giây, không gọi lại liên tục.
Phân trang
Một số API trả danh sách có phân trang (ví dụ /domain, /email). Dữ liệu phân trang nằm trong data:
{
"success": true,
"data": {
"number": 0,
"size": 20,
"totalPages": 5,
"totalElements": 42,
"content": [
{ "id": 1, "name": "example.vn", "status": "active" }
]
}
}
| Trường | Kiểu | Mô tả |
|---|---|---|
data.content | array | Danh sách bản ghi |
data.number | integer | Trang hiện tại (bắt đầu từ 0) |
data.size | integer | Số bản ghi mỗi trang |
data.totalPages | integer | Tổng số trang |
data.totalElements | integer | Tổng số bản ghi |
Content-Type và encoding
- Request: gửi
Content-Type: application/jsonvới POST, PUT, PATCH. - Response: JSON (
application/json). - Encoding: request và response đều dùng UTF-8. Tên miền có dấu (IDN) được hỗ trợ, API tự chuyển sang Punycode.
Gọi API từ máy chủ
Gọi API từ máy chủ (backend) của ứng dụng. Trình duyệt chỉ được gọi API trực tiếp từ trang developers.inet.vn, các trang khác bị chặn (CORS). API key cũng không nên nằm trong mã chạy ở trình duyệt vì ai mở trang cũng đọc được.