Skip to main content

​
エラーレスポンスの形式

APIエラー時は、以下の形式でエラー情報が返されます。 
{
    "error": {
        "code": "error_code",
        "message": "エラーの詳細メッセージ"
    }
}

​
HTTPステータスコード

​
400 Bad Request

リクエストパラメータに問題があります。 
{
    "error": {
        "code": "validation_error",
        "message": "The name field is required."
    }
}
対処方法: エラーメッセージを確認し、リクエストパラメータを修正してください。

​
401 Unauthorized

認証に失敗しました。APIキーを確認してください。
エラーコード説明対処方法
missing_keyAPIキーが未指定Authorization: Bearer {api_key} ヘッダーを追加
invalid_keyAPIキーが無効正しいAPIキーを使用しているか確認
disabled_keyAPIキーが無効化されている管理画面でAPIキーの状態を確認、必要なら再発行
missing_key
{
    "error": {
        "code": "missing_key",
        "message": "API key is required."
    }
}
invalid_key
{
    "error": {
        "code": "invalid_key",
        "message": "Invalid API key."
    }
}
disabled_key
{
    "error": {
        "code": "disabled_key",
        "message": "API key has been disabled."
    }
}

​
403 Forbidden

リソースへのアクセス権限がありません。 
{
    "error": {
        "code": "forbidden",
        "message": "You do not have permission to access this resource."
    }
}
対処方法: ライセンス共有ファネルなど、APIからの操作が制限されているリソースの場合に発生します。対象リソースの権限を確認してください。

​
404 Not Found

指定されたリソースが見つかりません。 
{
    "error": {
        "code": "not_found",
        "message": "Resource not found."
    }
}
対処方法: URLに含まれるID（funnel_id, step_id, page_id等）が正しいか確認してください。

​
429 Too Many Requests

レート制限を超過しました。 
{
    "error": {
        "code": "rate_limit_exceeded",
        "message": "Too many requests. Please try again later."
    }
}
対処方法: レスポンスヘッダーの X-RateLimit-Reset でリセット時刻を確認し、その時刻まで待ってからリトライしてください。 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000
レート制限の詳細は認証を参照してください。

​
500 Internal Server Error

サーバー内部でエラーが発生しました。 
{
    "error": {
        "code": "internal_error",
        "message": "An internal error occurred."
    }
}
対処方法: 時間をおいてリトライしてください。繰り返し発生する場合はサポートにお問い合わせください。

​
バリデーションエラーの詳細

​
要素構造エラー

elements方式のページでは、要素の階層ルールに違反するとバリデーションエラーになります。
ルール説明
elements 直下は section のみelements配列のルートにはsection要素だけを配置可能
section の子は row のみsectionのchildrenにはrow要素だけを配置可能
row の子は col のみrowのchildrenにはcol要素だけを配置可能
col の子はコンテンツ要素colのchildrenにtext, image, button等のコンテンツ要素を配置
正しい構造
{
    "elements": [
        {
            "type": "section",
            "children": [
                {
                    "type": "row",
                    "children": [
                        {
                            "type": "col",
                            "children": [
                                {"type": "text", "content": "<p>テキスト</p>"}
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
誤った構造（エラーになる）
{
    "elements": [
        {
            "type": "text",
            "content": "<p>テキスト</p>"
        }
    ]
}
上記の誤った例では、elements直下にtext要素を直接配置しているためエラーになります。必ず section > row > col の階層を経由してください。

​
content_type変更不可

ページ作成後に content_type を変更することはできません。elements で作成したページを raw_html に変更（またはその逆）しようとすると400エラーになります。 
{
    "error": {
        "code": "validation_error",
        "message": "content_type cannot be changed after creation."
    }
}
異なるcontent_typeのページが必要な場合は、新しいページを作成してください。

​
ページ更新時は全フィールドの送信が必要

ページ更新APIでは、変更箇所だけでなく全てのフィールドを含めて送信する必要があります。
未指定のフィールドはnullに上書きされます。更新前に必ずページ取得APIで現在の値を取得し、変更箇所のみ書き換えて全体を送信してください。
# 1. まず現在のページデータを取得
curl -X GET "https://api.utage-system.com/v1/funnels/{funnel_id}/steps/{step_id}/pages/{page_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# 2. 取得したデータの変更箇所を修正して送信
curl -X PUT "https://api.utage-system.com/v1/funnels/{funnel_id}/steps/{step_id}/pages/{page_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "更新後のタイトル",
    "page_title": "更新後のページタイトル",
    "pc_width": 800,
    "elements": [...]
  }'

​
リトライ戦略

APIエラー時の推奨リトライ戦略です。

​
429 Too Many Requests

X-RateLimit-Reset ヘッダーのUNIXタイムスタンプまで待ってからリトライします。 
待機時間 = X-RateLimit-Reset - 現在時刻（秒）

​
5xx サーバーエラー

指数バックオフでリトライします。
リトライ回数待機時間
1回目1秒
2回目2秒
3回目4秒
4回目8秒
5回目16秒
最大5回程度のリトライを推奨します。それでも解決しない場合はサポートにお問い合わせください。

​
リトライ不要なエラー

以下のエラーはリクエスト内容の修正が必要であり、同じリクエストをリトライしても解決しません。
  • 400 - リクエストパラメータを修正
  • 401 - APIキーを確認・再設定
  • 403 - リソースの権限を確認
  • 404 - リソースIDを確認
エラー発生時の調査には、レスポンスボディの error.code と error.message をログに記録しておくことを推奨します。