エラー
Oblic API がリクエストを拒否すると、HTTP ステータスが問題の種類を、本文が具体的な内容を示します。プログラムが処理できるコードと人が読めるメッセージがあり、多くの場合は対処方法も含みます。
エラーの構造
拒否の例
{
"status": "error",
"data": null,
"errors": [
{ "cd": "TO[0]", "message": "must be a well-formed email address" }
]
}
cdは大文字のコードです。メッセージは変更されることがあるため、処理の分岐にはコードを使います。errorsには問題ごとの項目が入り、二つのフィールドが誤っていれば両方を返します。- ルート実行前の拒否(キー、アドレス、スコープ、指定サブアカウントに関するもの)には
dataがありません。204応答には本文自体がありません。
ステータスコード
| ステータス | 意味 |
|---|---|
200, 201, 202, 204 | 完了、作成済み、送信・再実行をキューに登録、本文なしで完了 |
400 | フィールド、パラメーター、本文などリクエストが不正 |
401 | キーがないか認識されない。認証を参照 |
402 | INSUFFICIENT_BALANCE:マーケティング SMS・WhatsApp メッセージで支払元ウォレットが空。ログインコード、トランザクションメッセージ、返信は引き続き送信 |
403 | アドレス・スコープ・役割で許可されない、またはサブアカウントによるサブアカウント作成などアカウントが実行できない操作 |
404 | ルートがないか、そのアカウントに対象がない |
405, 415 | メソッド未対応(Allow で提示)、またはコンテンツタイプが不正。application/json を送信する |
409 | 別メッセージに使用済みの Idempotency-Key、既存テンプレートなどとの競合 |
413 | MESSAGE_TOO_LARGE:メッセージが送信可能なサイズを超える |
422 | 理解できるが実行不能。未確認の送信者、未承認テンプレート、受信を拒否した番号など |
429 | 制限に達した。Retry-After は秒単位の待ち時間 |
500 | Oblic 内部のエラー |
502 | WhatsApp 番号接続の一段階を Meta が拒否 |
503 | Oblic が依存するサービスが一時的に利用できない。何も実行していない |
メッセージや Webhookなど、各ページにそのルートのコードを掲載しています。
検証エラー
- 本文の必須フィールドがない、または不正な場合は、そのパスを大文字の
cd(TO、TO[0]、FROMNAME、ATTACHMENTS[0].FILENAMEなど)とし、違反した規則をmessageに返します。リストへの連絡先追加は例外で、不正な連絡先はパラメーター同様BAD_REQUESTです(連絡先リストを参照)。 - クエリ・パスパラメーターが不正な場合、例えば
limitが500、またはcursorが不正ならBAD_REQUESTとなり、messageが「limitは無効です」のように対象を示します。 - 本文がない、または JSON でない場合は
BAD_REQUEST:「本文がないか、このルートに対して有効な JSON ではありません」。 - 存在しないルートは
404 NOT_FOUND:「そのルートは存在しません」。 - ルートが認識しないフィールドは無視されます。
再試行
- 時間を置いて再試行するのは
429(Retry-Afterの秒数を待つ)、500、503、または応答がない場合です。待ち時間を徐々に長くします。送信の再試行には同じIdempotency-Keyを使い、一度だけ送信されるようにします。メッセージを参照してください。 - 先に修正が必要なのは他の
4xxです。同じリクエストは再び拒否されます。402ならウォレットに入金します。例外の422 OUTSIDE_PROMOTIONAL_HOURSにもRetry-Afterがあり、許可時間になれば同じ SMS を送信できます。