Định dạng phản hồi

Kiểu nội dung

Mọi endpoint đều trả về application/json mã hoá UTF-8, bất kể header Accept. Hãy gửi Content-Type: application/json trong các request có body.

Hai dạng, có chủ đích

Các endpoint dạng collection bọc payload trong data; endpoint trả về một đối tượng đơn trả các trường ở cấp cao nhất. Đây không phải chuyện ngẫu nhiên, và cần biết trước khi bạn viết parser:

{ "data": [ { "id": 47, "slug": "wavalid-realtime" } ] }

{ "balance": "5.230000" }

GET /v1/products thuộc dạng collection; GET /v1/balance và GET /v1/api-key thuộc dạng một đối tượng đơn. Các endpoint thời gian thực trả về chính đối tượng của lệnh gọi — request_id, status, results — ở cấp cao nhất.

Lỗi

Lỗi dùng một đối tượng cố định gồm hai trường:

{
  "code": "invalid_realtime_request",
  "message": "A realtime request cannot mix phone and email products."
}

Trường	Ý nghĩa
`code`	Định danh ổn định, máy đọc được. Hãy rẽ nhánh dựa trên giá trị này.
`message`	Chi tiết cho người đọc. Câu chữ có thể thay đổi; đừng parse nó.

Các giá trị code được ghi tài liệu theo từng endpoint, kèm HTTP status đi cùng — xem Mã lỗi để có danh sách đầy đủ.

Tiền

Tiền xuất hiện dưới hai dạng, và sự khác biệt này quan trọng khi bạn parse:

Vị trí	Kiểu	Ví dụ
`balance` trong `GET /v1/balance`	string	`"5.230000"`
`total_charged`, `charged_amount`, `refunded_amount` trong phản hồi thời gian thực	number	`0.004000`

Số dư được trả về dưới dạng chuỗi thập phân có độ chính xác cố định để không client nào gặp sai lệch làm tròn trên giá trị sắp được so với ngưỡng. Số tiền thời gian thực là số được làm tròn đến sáu chữ số thập phân — hãy coi là gần đúng khi vượt quá sáu chữ số thập phân.

Số tiền tính bằng USD. Ký hiệu tiền tệ không có trong payload.

Mốc thời gian

Mốc thời gian theo ISO 8601 ở UTC, có hậu tố Z:

2026-09-13T10:00:00Z

checked_at trên kết quả thời gian thực, và mốc thời gian của tác vụ trong phản hồi hàng loạt, đều tuân theo quy tắc này.

HTTP status không phải là kết quả

Có hai kiểu, và cả hai đều có chủ đích:

Thời gian thực: HTTP 200 nghĩa là lệnh gọi đã được thực thi, không phải mọi sản phẩm đều trả lời. Hãy đọc status và billing_status của từng mục.
Hàng loạt: một lần gửi trả về việc tác vụ được chấp nhận kiểu 202; công việc tiếp tục bất đồng bộ và kết quả chỉ tồn tại khi tác vụ đạt trạng thái kết thúc.

Quy tắc chung cho cả hai: status code cho biết có nên thử lại hay không, body cho biết điều gì đã xảy ra.

Mã lỗi — mọi code, theo từng endpoint
Giới hạn tần suất — các header trả về kèm 429