Mã lỗi

Khi request không được xử lý, response có data là null và error chứa chi tiết:

{
  "request_id": "req_01JBF8...",
  "data": null,
  "error": {
    "code": "QUOTA_INSUFFICIENT",
    "message": "Sản lượng eID còn lại không đủ",
    "details": { "quota_type": "eid_verify", "balance": 0, "required": 1 },
    "doc_url": "https://docs-everify.vtsi.vn/errors#quota_insufficient"
  }
}

code không đổi theo thời gian. Hãy xử lý lỗi theo code. message chỉ để đọc và có thể thay đổi.
doc_url dẫn tới đúng dòng của mã lỗi trong bảng dưới đây.

Lỗi không trừ lượt

Thẻ không hợp lệ không phải lỗi. Khi đó API trả 200 với result: INVALID và có trừ lượt.

Gửi lại sau lỗi

402, 429 và 5xx không giữ Idempotency-Key. Gửi lại cùng key thì request được xử lý lại như lần gọi mới.
INVALID_CARD_DATA và ID_NUMBER_MISMATCH được giữ lại. Gửi lại cùng key và cùng body sẽ nhận lại đúng lỗi cũ.

Chi tiết xem Gửi lại an toàn.

Bảng mã lỗi

HTTP	Mã	Nguyên nhân	Cách xử lý
400	`INVALID_REQUEST`	Thiếu trường hoặc trường sai định dạng. Danh sách lỗi nằm ở `details.violations[]`.	Sửa request theo `violations` rồi gửi lại.
400	`INVALID_CARD_DATA`	SOD hỏng, hoặc không tách được DS certificate hay số CCCD.	Đọc lại chip và gửi dữ liệu đầy đủ.
400	`ID_NUMBER_MISMATCH`	`id_number` khác số CCCD đọc được từ DG1/DG13.	Gửi đúng số CCCD của thẻ, hoặc bỏ trường `id_number`.
401	`UNAUTHENTICATED`	Thiếu hoặc sai `X-API-Key`.	Kiểm tra key và tên header.
402	`QUOTA_INSUFFICIENT`	Đơn vị sở hữu ứng dụng không đủ lượt. `details` có `quota_type`, `balance`, `required`.	Liên hệ quản trị đơn vị để được cấp thêm lượt.
403	`APP_DISABLED`	Ứng dụng đã bị thu hồi hoặc hết hạn.	Tạo ứng dụng mới hoặc gia hạn ứng dụng.
403	`IP_NOT_ALLOWED`	Ứng dụng đã giới hạn IP và IP gọi không nằm trong danh sách.	Thêm IP máy chủ vào danh sách được phép.
403	`ENTERPRISE_SUSPENDED`	Đơn vị hoặc đơn vị cấp trên đang bị tạm ngưng.	Liên hệ quản trị.
403	`ORIGIN_NOT_ALLOWED`	Request được gửi từ trình duyệt, trên một trang web không phải trang tài liệu eVerify.	Gọi API từ máy chủ của bạn.
409	`IDEMPOTENCY_CONFLICT`	Cùng `Idempotency-Key` nhưng body khác lần trước.	Dùng key mới cho request mới.
409	`REQUEST_IN_PROGRESS`	Cùng key và lần gọi trước chưa xử lý xong.	Chờ vài giây rồi gửi lại cùng key.
413	`PAYLOAD_TOO_LARGE`	Body lớn hơn 1 MB.	Bỏ các data group không cần, ví dụ DG2.
429	`RATE_LIMITED`	Vượt giới hạn request/phút của ứng dụng (mặc định 120).	Chờ theo `Retry-After` rồi gửi lại.
500	`INTERNAL_ERROR`	Lỗi hệ thống.	Gửi lại cùng `Idempotency-Key`. Nếu vẫn lỗi, báo VTS kèm `request_id`.
502	`PROVIDER_ERROR`	Hệ thống xác thực phía sau trả lỗi, chưa có kết luận.	Chờ vài giây rồi gửi lại cùng `Idempotency-Key`.
503	`PROVIDER_UNAVAILABLE`	Tạm thời không kết nối được hệ thống xác thực.	Chờ theo `Retry-After` rồi gửi lại.
504	`PROVIDER_TIMEOUT`	Quá thời gian xử lý.	Gửi lại cùng `Idempotency-Key`.

Gửi lại sau lỗi​

Bảng mã lỗi​

Gửi lại sau lỗi

Bảng mã lỗi