AppRun Dedicated API は仕様が厳密で、必須パラメータや上限を外すと即エラーになります。
本記事では、実際に遭遇したエラーログをそのまま載せつつ、原因 → 対策 → 再発防止の順で整理します。
先に結論：Dedicated API は「仕様が厳密でエラーが素直」。
だからこそ 上限/必須値（maxItems / name長 / service principal / env secret）を最初に固定するのが最短です。
この記事でわかること
maxItemsが必須かつ 上限 30 の罠- Cluster / ASG / LB / App の 名前は 20 文字以内
- Service Principal がないと 500 で詰むケース
envに secret フィールド必須の落とし穴TimeoutSecondsの バリデーションで落ちる条件
1) maxItems が必須＆上限 30（ListClusters が即死する）
発生エラー
HTTP 400 Bad Request: {"error_message":"operation ListClusters: decode params: query: \"maxItems\" not set"}HTTP 400 Bad Request: {"error_message":"operation ListClusters: decode params: query: \"maxItems\": int: value 100 greater than 30"}原因
ListClustersではmaxItemsが 必須- さらに値は 30 が上限（31以上は 400）
対策（結論）
- 必ず
maxItems=30を付与する
例
GET /clusters?maxItems=302) 名前の文字数制限（<= 20）｜Cluster/ASG/LB/App 全部に効く
発生エラー（代表）
HTTP 400 Bad Request: {"error_message":"operation CreateCluster: decode request: validate: invalid: name (string: len 24 greater than maximum 20)"}HTTP 400 Bad Request: {"error_message":"operation CreateAutoScalingGroup: decode request: validate: invalid: name (string: len 23 greater than maximum 20)"}HTTP 400 Bad Request: {"error_message":"operation CreateLoadBalancer: decode request: validate: invalid: name (string: len 22 greater than maximum 20)"}原因
- name フィールドが 20文字制限
- Cluster / AutoScalingGroup / LoadBalancer / Application あたりで横断的に引っかかる
対策（結論）
- 命名ルールを最初から 20 文字以内に固定する
再発防止Tips（おすすめ命名パターン）
proj-env-roleを短縮する
例：ss-prd-fe/ss-prd-be/ss-stg-fe- suffix を短縮：
frontend→fe、backend→be、production→prd
命名は「後で直す」が一番コスト高いので、最初に縛るのが正義。
3) Service Principal 必須｜無いと 500 で止まることがある
発生エラー
HTTP 500 Internal Server Error: {"status":500,"title":"failed to register cluster service principal"}[apprun-dedicated] service principal id is missing or placeholder原因
- クラスタ登録時に Service Principal が必要
- 未設定 or プレースホルダだと 内部登録に失敗して 500 になることがある
対策（結論）
- IAM で Service Principal ID を発行
- 環境変数や設定値に 明示的にセットする（暗黙期待しない）
4) env に secret フィールド必須｜「secret://」でも自動ではない
発生エラー
HTTP 400 Bad Request: {"error_message":"operation CreateApplicationVersion: decode request: decode application/json: decode CreateApplicationVersion: callback: decode field \"env\": callback: invalid: secret (field required)"}原因
envを送る場合、各項目にsecretが 必須フィールドsecret://を使っていても、API 側が secret を推論しないケースがある
対策（結論）
envを送信するなら 必ずsecretを明示- ルール：
secret://を含む値はsecret=trueにする（クライアント側で）
例（イメージ）
{
"env": [
{ "key": "DB_PASSWORD", "value": "secret://xxx", "secret": true },
{ "key": "APP_ENV", "value": "production", "secret": false }
]
}5) TimeoutSeconds バリデーション｜許容値以外は 400
発生エラー
code: 400, message: Validation Error, inner_error: {domain: global, reason: application invalid field, message: invalid TimeoutSeconds, location_type: body, location: TimeoutSeconds}原因
TimeoutSecondsは 許容される値が固定（範囲/候補がある）- 想定外の値だと “invalid TimeoutSeconds” で 400
対策（結論）
- AppRun 側で許容される値のみをセットする
- 実装上は「入力値をそのまま投げる」のではなく、**バリデーション（許容リスト or 範囲チェック）**を入れる
まとめ｜Dedicated API は「仕様の前提をコードに埋める」と安定する
AppRun Dedicated API は、
必須パラメータと**制約（上限・文字数・必須フィールド）**を外すと素直に落ちます。
maxItems=30を必ず付ける（必須＆上限30）- name は 20 文字以内（Cluster/ASG/LB/App）
- Service Principal を必ず用意して明示
- env は
secret必須（自動推論に頼らない） - TimeoutSeconds は許容値のみ
一度踏むと二度と踏まない系のエラーなので、**「制約を設定にする」より「制約をコードに固定」**した方が早いです。
FAQ
Q. なぜ maxItems は必須なんですか？
A. ListClusters のクエリパラメータとして必須扱いになっており、未指定は decode 段階で弾かれます（400）。
Q. “name 20文字制限” はどこに効きますか？
A. Cluster / AutoScalingGroup / LoadBalancer / Application など、複数リソースにまたがって効きます。命名規約を短縮前提にするのがおすすめです。
Q. secret:// を使ってるのに secret が必須なのはなぜ？
A. API デコード時に secret フィールドが required 扱いのため、値から推論されません。クライアント側で secret=true/false を必ず付ける必要があります。