Qiita APIで記事更新が失敗する理由｜PATCHで消える項目

Posted at 2026-10-06

Qiita API v2の PATCH /api/v2/items/:item_id を使って記事更新を行った際、差分だけを送ったつもりが 400 Bad Request で拒否されたり、既存のタグが綺麗さっぱり消去されたりする問題に直面することがあります。本記事では公式仕様に基づき、PATCHリクエストにおける項目の消失仕様やエラー原因、Pythonによる安全な更新ロジックを解説します。

PATCHリクエストでも必須項目の送信が必要: Qiita APIの PATCH /api/v2/items/:item_id エンドポイントは、title と body が必須パラメータであり、差分のみを送信すると 400 Bad Request となる。
省略された項目の上書きリスク: tags などの配列型・オブジェクト型パラメータは、指定方法を誤ると既存のデータ構造全体が上書き・消去される。
Safe PATCHパターンの徹底: 事前に GET /api/v2/items/:item_id で現在の記事情報を取得し、変更したい項目だけをマージして送信することで、データ消失やステータスコードエラー（400/401/403/429）を防ぐことができる。

なぜQiita APIのPATCHリクエストで記事更新エラーやデータ消去が起きるのか

RESTful APIにおける一般的なHTTP PATCH メソッドは「リソースの一部分だけを変更する（差分更新）」という概念で設計されることが多いです。しかし、Web APIの標準仕様や各サービスの実装によって、リクエストボディに含まれなかったフィールドの扱いには大きな違いが存在します。

Qiita API v2における記事更新エンドポイント PATCH /api/v2/items/:item_id では、送信されたJSONオブジェクトのキーに基づいてリソースが更新されます。ここで問題となるのが「必須パラメータの存在」と「配列・連想配列の全置換仕様」です。

一般的に「タイトルだけを変更したいから { "title": "新しいタイトル" } というJSONをPATCHで送る」という実装を行い勝ちですが、Qiita API v2のドキュメントに記載されている通り、PATCH /api/v2/items/:item_id では body と title の両方が必須（required）パラメータとして定義されています。そのため、body を省略してリクエストを送信した時点で、APIサーバーから即座に 400 Bad Request エラーが返却され、更新処理全体が失敗します。

さらに、必須ではないパラメータ（例えば tags や organization_url_name など）についても、リクエストボディでの指定内容や省略時の解釈によって、既存記事に設定されていたデータが消えてしまうリスクを孕んでいます。Web UIでのエディタ操作とは異なり、API経由でのリクエストは送信されたリクエストボディがそのまま評価されるため、プログラム側の実装ミスがダイレクトにデータの欠損へとつながります。

PATCHで消える項目と注意すべきパラメータ仕様

記事更新時にリクエストボディへ含めるJSONデータの中で、特に注意が必要なパラメータとその挙動について詳しく解説します。

1. `body` と `title`（必須パラメータ）

これらは記事の本文（Markdown文字列）とタイトルを表すパラメータです。両者とも更新リクエストにおいて必須項目に指定されています。タイトルだけを修正したい場合であっても、現行の body の内容を含めてリクエストを作成しなければなりません。片方を欠いた状態でリクエストを送ると、HTTPステータスコード 400 Bad Request が返され、処理が中断します。

2. `tags`（配列パラメータの置換仕様）

tags パラメータは、記事に付与するタグのリストを指定する配列オブジェクトです。

"tags": [
  {"name": "Python", "versions": ["3.10"]},
  {"name": "Qiita"}
]

tags パラメータをリクエストに含めて更新を行う場合、既存のタグに対して「追加・削除」の差分適用が行われるのではなく、送信した配列の内容で完全に上書きされます。例えば、もともと「Python」「API」「Qiita」という3つのタグが設定されていた記事に対して、tags に [{"name": "Python"}] のみを指定して送信すると、「API」と「Qiita」のタグは記事から削除されます。また、空配列 [] を送信した場合はタグがゼロ件となり、バリデーションエラーまたはタグ全削除の対象となります。

3. `private`（限定共有フラグ）

private は記事が限定共有状態か否かを示すブーリアン値（true または false）です（個人版Qiitaでのみ有効）。更新時に private の指定を省略した場合、既存の状態（限定共有なのか公開なのか）がそのまま維持されるか、あるいは意図しないデフォルト値で上書きされるリスクを考慮する必要があります。限定共有記事として運用している記事の更新時には、明示的に "private": true を保持して送信することが安全です。

4. Qiita Team専用パラメータ（`group_url_name`, `coediting`）

組織向けサービスであるQiita Teamを利用している場合、group_url_name（所属グループのURL名）や coediting（共同編集モードフラグ）といったパラメータが存在します。これらはQiita Team専用機能であり、個人版Qiita（qiita.com）のエンドポイントに対して送信しても無視されるか、不適切なリクエストとしてエラーとなる可能性があります。Qiita Teamでグループ指定を解除して全体公開に変更したい場合は、group_url_name に null を指定して送信する仕様となっています。

Qiita API PATCHパラメータの更新挙動と消失リスク一覧

以下の表は、PATCH /api/v2/items/:item_id エンドポイントへ渡す各パラメータの型、必須性、省略時および空値指定時の挙動をまとめた早見表です。

パラメータ名	型	必須	省略時の挙動	空値・空配列指定時の影響	適用範囲
`title`	string	必須	`400 Bad Request` エラーが発生する	空文字 `""` はバリデーションエラー	全体
`body`	string	必須	`400 Bad Request` エラーが発生する	空文字 `""` はバリデーションエラー	全体
`tags`	array	任意	既存のタグ情報が保持される	空配列 `[]` 指定時、タグ削除または400エラー	全体
`private`	boolean	任意	既存の公開/限定共有状態を維持	ブーリアン型以外は400エラー	個人版Qiita専用
`group_url_name`	string / null	任意	既存のグループ所属状態を維持	`null` 指定時、グループ指定を解除	Qiita Team専用
`coediting`	boolean	任意	既存の共同編集モード状態を維持	ブーリアン型以外は400エラー	Qiita Team専用
`organization_url_name`	string / null	任意	既存のOrganization紐付けを維持	`null` 指定時、Organization紐付け解除	全体

ステータスコード別：記事更新失敗の原因と解決策

Qiita API v2から返却されるレスポンスのHTTPステータスコードを正しくハンドリングすることで、更新失敗の原因を特定できます。発生しやすいステータスコードとその原因・対処法は以下の通りです。

ステータスコード	エラー名	主な発生原因	解決策
400	Bad Request	リクエストボディに `title` や `body` が存在しない。JSONの構文エラー。`Content-Type` ヘッダーの欠落。	リクエストボディに必須パラメータがすべて含まれているか確認。`Content-Type: application/json` を設定する。
401	Unauthorized	アクセストークンが設定されていない、または無効・期限切れである。	`Authorization: Bearer <トークン>` ヘッダーが正しく設定されているか確認し、トークンを再発行する。
403	Forbidden	アクセストークンのスコープ不足。他人の記事を更新しようとしている。	トークンに `write_qiita`（Teamの場合は `write_qiita_team`）スコープが付与されているか確認する。
404	Not Found	指定した `item_id` の記事が存在しない。	エンドポイントURLに含まれる `:item_id` の文字列に誤りがないか確認する。
429	Too Many Requests	APIのレート制限（回数上限）を超過した。	レート制限の解除時間まで待機するか、リクエスト頻度を抑制するバックオフ処理を実装する。
500	Internal Server Error	Qiita側のサーバー内部エラー。	一時的な障害の可能性があるため、時間をおいてリトライする。

Safe PATCHの実装：Python（requests）による安全な更新テンプレート

消える項目を防ぎ、400 Bad Request を回避するための最適なプラクティスは**「GETで現在の記事情報を取得し、必要な箇所のみを差し替えてからPATCHで送信する」**（Safe PATCHパターン）というアプローチです。

以下に、Pythonの requests ライブラリを使用したコピー＆ペーストで動作する最小限のコード例を示します。環境変数 QIITA_TOKEN からアクセストークンを読み込んで処理を行います。

import os
import sys
import requests

# 環境変数からアクセストークンを取得
QIITA_TOKEN = os.environ.get("QIITA_TOKEN")
if not QIITA_TOKEN:
    print("エラー: 環境変数 QIITA_TOKEN が設定されていません。")
    sys.exit(1)

# 対象の記事IDとAPIエンドポイント
ITEM_ID = "c686397e4a0f4f11683d"  # 対象記事の20桁のIDを指定
BASE_URL = "https://qiita.com/api/v2/items"
ITEM_URL = f"{BASE_URL}/{ITEM_ID}"

headers = {
    "Authorization": f"Bearer {QIITA_TOKEN}",
    "Content-Type": "application/json"
}

# 1. 現在の記事データをGETリクエストで取得
get_response = requests.get(ITEM_URL, headers=headers)

if get_response.status_code == 401:
    print("エラー 401: 認証に失敗しました。アクセストークンを確認してください。")
    sys.exit(1)
elif get_response.status_code == 403:
    print("エラー 403: 権限が不足しています。スコープを確認してください。")
    sys.exit(1)
elif get_response.status_code == 404:
    print("エラー 404: 指定された記事が存在しません。")
    sys.exit(1)
elif get_response.status_code == 429:
    print("エラー 429: レート制限を超過しました。時間をおいて再試行してください。")
    sys.exit(1)
elif get_response.status_code != 200:
    print(f"エラー {get_response.status_code}: 記事の取得に失敗しました。")
    sys.exit(1)

current_item = get_response.json()

# 2. 既存のデータをベースに、変更したいフィールドのみを更新
# 必須項目（title, body）やtagsを既存データから引き継ぐことで削除を防ぐ
updated_title = current_item["title"] + "（更新済み）"
updated_body = current_item["body"] + "\n\n※この記事はAPI経由で更新されました。"
existing_tags = current_item["tags"]  # タグの配列構造を保持

payload = {
    "title": updated_title,
    "body": updated_body,
    "tags": existing_tags,
    "private": current_item.get("private", False)
}

# 3. PATCHリクエストを送信して記事を更新
patch_response = requests.patch(ITEM_URL, headers=headers, json=payload)

print(f"HTTP Status Code: {patch_response.status_code}")

if patch_response.status_code == 200:
    print("記事の更新が正常に完了しました。")
    updated_data = patch_response.json()
    print(f"更新後のタイトル: {updated_data['title']}")
elif patch_response.status_code == 400:
    print("エラー 400: リクエストパラメータが不正です。必須項目が含まれているか確認してください。")
    print(patch_response.text)
elif patch_response.status_code == 403:
    print("エラー 403: 更新権限がないか、write_qiita スコープが付与されていません。")
elif patch_response.status_code == 429:
    print("エラー 429: レート制限オーバーです。")
else:
    print(f"更新失敗: {patch_response.status_code}")
    print(patch_response.text)

レート制限・スコープ・廃止APIの罠と自動化の設計指針

プログラムによる記事の更新自動化やスクリプト運用を行う場合、パラメータの指定方法以外にも注意すべきAPI全体の制限事項や仕様が存在します。

1. APIのレート制限（Rate Limit）

Qiita API v2では、サービスの安定運用と保護を目的としてクライアントに対するアクセス回数制限を設けています。

認証済みリクエスト: 1,000回 / 時間
未認証リクエスト: 60回 / 時間（IPアドレス単位）

記事更新（PATCH）を行うには認証が必須であるため、上限は1時間あたり1,000回となります。大量の記事を一括更新するバッチ処理などを実装する際は、リクエスト間隔に適切なスリープ（time.sleep）を挿入し、レスポンスヘッダーに含まれる制限状況を確認する設計にしてください。

2. ページネーション（Pagination）

記事一覧を取得してループ処理で更新を行う場合、一覧取得エンドポイント（GET /api/v2/authenticated_user/items や GET /api/v2/items）のページネーション仕様を考慮する必要があります。

指定可能パラメータ: page（1?100、デフォルト: 1）、per_page（1?100、デフォルト: 20）
1ページあたり最大100件まで取得可能であり、これを超えるデータを扱う場合は複数ページに分けてリクエストを発行します。

3. アクセストークンの認証スコープ（Scope）

APIで利用するアクセストークンには、実行可能な操作を制限するスコープが紐付いています。スコープは以下の4種類が定義されています。

read_qiita: 個人版Qiitaの関連データを読み込む
read_qiita_team: Qiita Team専用のデータを読み込む
write_qiita: 個人版Qiitaにデータを書き込む・更新する
write_qiita_team: Qiita Team専用にデータを書き込む・更新する

個人版Qiitaで記事の更新（PATCH /api/v2/items/:item_id）を行うには、トークン発行時に write_qiita スコープを有効にしておく必要があります。スコープが不十分なトークンでアクセスした場合は 403 Forbidden エラーが発生します。

4. 廃止済み機能・エンドポイントへの注意

旧バージョンのドキュメントや過去の技術ブログを参照してスクリプトを作成する際、既に廃止されているエンドポイントを使用しないよう注意が必要です。

Project（プロジェクト）関連機能: 2022年10月1日にAPI機能が廃止されました（GET/POST/PATCH /api/v2/projects 等は利用不可）。
thank / Team Like 関連機能: 2020年11月4日に廃止されました（PUT/DELETE /api/v2/comments/:comment_id/thank 等は利用不可）。

これらは現行のQiita API v2では利用できないため、古いプログラムの流用時はエンドポイントの存在を確認してください。

レート制限とエラー判定を考慮したロバストな記事更新スクリプト

以下のPythonコードは、複数記事の更新処理や自動化スクリプトで実用的に使えるように、HTTPステータスコードの判定（400, 401, 403, 429）およびレート制限ヘッダーの確認を組み込んだ高度な実装例です。

import os
import sys
import time
import requests

QIITA_TOKEN = os.environ.get("QIITA_TOKEN")
if not QIITA_TOKEN:
    print("エラー: QIITA_TOKEN が設定されていません。")
    sys.exit(1)

HEADERS = {
    "Authorization": f"Bearer {QIITA_TOKEN}",
    "Content-Type": "application/json"
}

def get_item_safely(item_id):
    """記事の現在の情報を安全に取得する関数"""
    url = f"https://qiita.com/api/v2/items/{item_id}"
    response = requests.get(url, headers=HEADERS)
    
    # レート制限情報の確認
    rate_remaining = response.headers.get("Rate-Remaining")
    print(f"[API Info] 残りリクエスト可能回数: {rate_remaining}")

    if response.status_code == 200:
        return response.json()
    elif response.status_code == 401:
        print("エラー 401: トークンが無効です。")
    elif response.status_code == 403:
        print("エラー 403: スコープ権限が不足しています。")
    elif response.status_code == 404:
        print(f"エラー 404: 記事 ID '{item_id}' は見つかりません。")
    elif response.status_code == 429:
        print("エラー 429: レート制限に達しました。処理を中断します。")
    else:
        print(f"HTTPエラー {response.status_code}: {response.text}")
    
    return None

def update_item_safely(item_id, new_title=None, new_body=None, new_tags=None):
    """
    既存データを保持しながら、安全に記事を更新する関数
    """
    # 現在データの取得
    current_data = get_item_safely(item_id)
    if not current_data:
        print("更新処理をスキップします。")
        return False

    # 差分マージ処理（引数で指定がなければ既存の値を採用して消去を防ぐ）
    payload = {
        "title": new_title if new_title is not None else current_data["title"],
        "body": new_body if new_body is not None else current_data["body"],
        "tags": new_tags if new_tags is not None else current_data["tags"],
        "private": current_data.get("private", False)
    }

    url = f"https://qiita.com/api/v2/items/{item_id}"
    response = requests.patch(url, headers=HEADERS, json=payload)

    if response.status_code == 200:
        print(f"成功: 記事 '{item_id}' を正常に更新しました。")
        return True
    elif response.status_code == 400:
        print("エラー 400: パラメータ不備による更新失敗。")
        print(f"詳細: {response.text}")
    elif response.status_code == 403:
        print("エラー 403: 記事の更新権限がありません。")
    elif response.status_code == 429:
        print("エラー 429: レート制限を超過しました。")
    else:
        print(f"エラー {response.status_code}: {response.text}")

    return False

if __name__ == "__main__":
    # テスト実行例（実在する記事IDに置き換えて実行）
    target_item_id = "c686397e4a0f4f11683d"
    
    # タイトルのみを変更したい場合でも、関数内部でbodyとtagsが自動補完されてSafe PATCHが行われる
    success = update_item_safely(
        item_id=target_item_id,
        new_title="Pythonから安全に更新された記事タイトル"
    )
    
    if success:
        print("処理が正常終了しました。")
    else:
        print("処理中にエラーが発生しました。")

まとめ

Qiita API v2における PATCH /api/v2/items/:item_id を使った記事更新では、HTTP PATCHという標準メソッドの名称から「一部のフィールドだけを送ればよい」と誤解しがちですが、実際にはいくつかの厳格なルールが存在します。

必須パラメータのクリア: 記事更新時には title と body が必須であり、省略すると 400 Bad Request になる。
上書きリスクの回避: tags などの配列項目は部分更新ではなく全置換となるため、指定なしや空値送信によって設定済みデータが削除されるリスクがある。
Safe PATCHパターンの採用: 更新前に GET /api/v2/items/:item_id で既存データを取得し、変更不要な項目を補完したうえで PATCH リクエストを送信する実装を徹底する。
API制限・権限の管理: 認証トークンの write_qiita スコープや、1時間あたり1,000回のリクエストレート制限（429エラー）を正しく考慮してエラーハンドリングを構築する。

APIの正確な仕様を理解し、安全なデータマージ処理を組み込むことで、意図しないデータの消失やリクエストエラーを防ぎ、堅牢なAPI連携プログラムを構築できます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up