AppCotton SDK および REST API では、
ライセンス状態・使用状況・認証結果 を統一的に扱うために
標準化された エラーコード体系 を採用しています。
これにより、プラグイン開発者は複雑な状態判定を行わず、
UI 表示とロジック分岐を エラーコードベース で簡潔に実装できます。
エラーコード設計の意図
| 目的 | 内容 |
|---|---|
| UI表示を簡潔にする | 状態ごとに明確なメッセージ・案内導線が作れる |
| SDK内部の分岐を統一 | is_premium 判定などを単純な bool として扱える |
| APIレスポンスを安定化 | 外部統合（SaaS / CLI / ライセンス配布など）に強い |
基本構造（REST API の失敗レスポンス）
{
"error": "error_code_here",
"message": "ユーザーに表示する説明文",
"http_status": 400
}
SDK 側では以下の形にラップされます：
[
'success' => false,
'error' => 'error_code_here',
'message' => 'ユーザー向けの説明'
]
エラー分類一覧
A. ライセンスキーに関するエラー
| error | 意味 | 対処 |
|---|---|---|
invalid_license | ライセンスキーが存在しない | 入力ミス / キー再確認 |
wrong_product | product_slug が一致していない | 他製品のキーを使用しようとしている |
revoked_license | 管理者により利用権が取り消し | サポート案内が必要 |
B. ライセンス状態に関するエラー
| error | 意味 | UIでの案内 |
|---|---|---|
expired_license | 有効期限切れ | 「更新する」ボタンを提示 |
suspended_license | 一時停止中（決済保留等） | Stripe請求・決済状況を確認 |
inactive_license | 有効化が完了していない | 「このサイトで有効化」 ボタンを提示 |
C. ドメイン / アクティベーション制御
| error | 意味 | 対応 |
|---|---|---|
domain_limit_reached | 使用可能サイト数の上限に達した | ドメイン解除 UI へ誘導 |
domain_not_registered | 未アクティベート状態 | activate() を呼び出す |
domain_blacklisted | 不正利用・アクセスブロック | 管理者対応が必要 |
D. API / ネットワーク / セキュリティ
| error | 意味 | 詳細 |
|---|---|---|
network_error | サーバーに到達できない | タイムアウト / 一時的な障害 |
invalid_nonce | WordPress認証失敗 | ログインセッション切れ |
rate_limited | 連続アクセス制限 | 一定時間後に再試行 |
server_error | サーバ内部エラー | 管理者確認が必要 |
UI メッセージテンプレート（推奨）
| 状況 | 推奨文言 |
|---|---|
invalid_license | 「ライセンスキーが正しくありません。入力内容をご確認ください。」 |
expired_license | 「有効期限が切れています。更新することで再度利用可能になります。」 |
domain_limit_reached | 「利用可能なサイト数の上限に達しています。不要なサイトを解除してください。」 |
revoked_license | 「このライセンスは利用停止されています。サポートへお問い合わせください。」 |
network_error | 「通信に失敗しました。ネットワーク状態を確認して再度お試しください。」 |
is_premium() とエラーの関係
is_premium() は内部的に validate() を実行しますが、
UI側でエラーメッセージを出す必要はありません。
| 状態 | is_premium | 推奨挙動 |
|---|---|---|
| active | true | プレミアム機能を表示 |
| expired / revoked / domain_limit_reached | false | 「アップグレード / 更新 / 解除誘導」UIへ |
UI設計は「成功は silent / 失敗時のみ案内」という思想です。
API / SDK エラーの流れ
validate() 実行
↓
REST API応答を受け取る
↓
error フィールドがあれば is_premium = false
↓
error に応じて UI で適切な導線を提示
開発チェックリスト
errorは コードベースで分岐し UI を切り替えるmessageはユーザー向けにそのまま表示して問題ない内容revokedとexpiredを UI で区別しているdomain_limit_reachedのとき解除導線が表示される- ネットワーク系は
再試行 + 案内を表示
まとめ
• AppCotton は標準化されたエラーコード体系を採用
• is_premium() は内部的にエラーを吸収し「true/false」で返す
• UI で必要なのは error の種類に応じた案内導線
• domain_limit_reached / expired / revoked は特に重要