Формат ответа

Тип содержимого

Каждый эндпоинт возвращает application/json в кодировке UTF-8 независимо от заголовка Accept. В запросах с телом передавайте Content-Type: application/json.

Две формы — намеренно

Эндпоинты-коллекции оборачивают полезную нагрузку в data; эндпоинты одного объекта возвращают свои поля на верхнем уровне. Это не случайность, и об этом стоит знать до того, как вы напишете парсер:

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

{ "balance": "5.230000" }

GET /v1/products — случай коллекции; GET /v1/balance и GET /v1/api-key — случай одного объекта. Эндпоинты реального времени возвращают объект самого вызова — request_id, status, results — на верхнем уровне.

Ошибки

Ошибки используют фиксированный объект из двух полей:

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

Поле	Значение
code	Стабильный машиночитаемый идентификатор. Ветвите логику по нему.
message	Подробности для чтения человеком. Формулировка может меняться; не разбирайте её парсером.

Значения code описаны для каждого эндпоинта вместе с HTTP-статусом, с которым они приходят — полный список см. в Error codes.

Деньги

Деньги встречаются в двух формах, и при разборе ответа разница важна:

Где	Тип	Пример
balance в GET /v1/balance	string	"5.230000"
total_charged, charged_amount, refunded_amount в ответах реального времени	number	0.004000

Баланс передаётся строкой с фиксированной точностью, чтобы ни один клиент не увидел артефакт округления в значении, которое собирается сравнивать с порогом. Суммы реального времени — это числа, округлённые до шести знаков после запятой; за пределами шести знаков считайте их приблизительными.

Суммы указаны в USD. Символ валюты в полезную нагрузку не включается.

Метки времени

Метки времени — ISO 8601 в UTC с суффиксом Z:

2026-09-13T10:00:00Z

checked_at в результате реального времени и метки времени задачи в массовых ответах следуют этому правилу.

HTTP-статус — это не результат

Есть два шаблона, и оба намеренны:

• Реальное время: HTTP 200 означает, что вызов был выполнен, а не что ответил каждый продукт. Читайте status и billing_status каждой записи.
• Массовые проверки: отправка возвращает принятие задачи в стиле 202; работа продолжается асинхронно, и результат существует только после того, как задача достигнет конечного статуса.

Правило в обоих случаях: код статуса говорит, нужно ли повторять запрос, а тело — что произошло.

Дальше

• Error codes — каждый code, по эндпоинтам
• Rate limits — заголовки, которые приходят с 429