レスポンス形式

コンテンツタイプ

すべてのエンドポイントは、Accept ヘッダーに関係なく、UTF-8 でエンコードされた application/json を返します。ボディを伴うリクエストでは Content-Type: application/json を送信してください。

意図的に分けた2つの形状

コレクションエンドポイントはペイロードを data で包みます。単一オブジェクトのエンドポイントは各フィールドをトップレベルで返します。これは偶然ではなく、パーサーを書く前に知っておく価値があります。

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

{ "balance": "5.230000" }

GET /v1/products はコレクションの例で、GET /v1/balance と GET /v1/api-key は単一オブジェクトの例です。リアルタイムエンドポイントは、呼び出し自身のオブジェクト — request_id、status、results — をトップレベルで返します。

エラー

エラーは固定の2フィールドのオブジェクトを使用します。

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

フィールド	意味
code	安定した機械可読な識別子。これで分岐します。
message	人間が読める詳細。文言は変更される可能性があるため、パースしないでください。

code の値は、それが返される HTTP ステータスとともにエンドポイントごとに記載されています。全一覧は エラーコード を参照してください。

金額

金額は2つの形式で現れ、その違いはパース時に重要です。

場所	タイプ	例
GET /v1/balance の balance	string	"5.230000"
リアルタイムレスポンスの total_charged、charged_amount、refunded_amount	number	0.004000

残高は固定精度の10進数文字列として出力されるため、しきい値と比較しようとしている値に丸め誤差が現れることはありません。リアルタイムの金額は小数点以下6桁に丸められた数値です。6桁を超える部分は近似値として扱ってください。

金額は USD で表されます。通貨記号はペイロードに含まれません。

タイムスタンプ

タイムスタンプは UTC の ISO 8601 で、Z サフィックスが付きます。

2026-09-13T10:00:00Z

リアルタイム結果の checked_at、およびバルクレスポンスのタスクタイムスタンプがこれに従います。

HTTP ステータスは結果ではない

2つのパターンがあり、どちらも意図的です。

• リアルタイム: HTTP 200 は呼び出しが実行されたことを意味し、すべてのプロダクトが応答したことを意味しません。status と各エントリの billing_status を確認してください。
• バルク: 送信は 202 系のタスク受付を返します。処理は非同期で継続し、結果はタスクが終端ステータスに到達して初めて確定します。

どちらの場合もルールは同じです。ステータスコードはリトライすべきかを示し、ボディは何が起きたかを示します。

次のページ

• エラーコード — エンドポイントごとのすべての code
• レート制限 — 429 とともに返されるヘッダー