AIものさし

Airtable APIでLinked recordが422になるとき、record IDの配列形式と参照先を確認する

Airtable REST APIでLinked record fieldの値を更新するとき、公式のField Types資料が示す値の形はrecord ID文字列の配列です。

AIものさし編集部

目次

まず結論：Linked recordはrecord ID文字列の配列で渡す

Airtable REST APIでLinked record fieldの値を更新するとき、公式のField Types資料が示す値の形はrecord ID文字列の配列です。たとえば1件を関連付ける場合も、field valueは1つの文字列ではなく、record IDを含む配列として送ります。複数件なら配列に各record IDを入れます。文字列の見た目だけでなく、対象フィールドが本当にLinked record型か、IDが参照先tableのrecord IDかを確認してください。

ただし、HTTP 422だけで「配列形式が原因」と確定はできません。Airtableの共通troubleshootingは422をinvalid requestとして説明し、response JSONのerror type/messageでspecific validationを確認するよう案内しています。Linked record参照先のrecordが見つからずAirtableがforeign table側にrecordを作ろうとする場面では、synced tableまたはformula primary fieldのため作成できないと403 invalid_permissionsになる場合もあります。実際のHTTP statusとerror bodyを見てから分岐します。

まずresponse bodyと更新対象を保存する

JSONのerror objectからtypeとmessageを確認します。HTTP 422、INVALID_VALUE_FOR_COLUMN等の具体的error、field名、table IDなどを記録し、tokenや不要なrecord内容を伏せます。Airtable公式資料は4xxを主にclient側のrequest issueとして扱い、422 invalid requestではrequest dataがinvalidで、詳細message/codeが原因特定に役立つと説明しています。

表は横にスクロールできます

確認する値見るもの判断への使い方
HTTP status422、403などpayload validationとaccess/permissionを分ける
error.typeINVALID_VALUE_FOR_COLUMN等Airtableが返した分類を保持
error.messagefield/値の具体的理由書き込み対象や型を絞る
Base ID / Table IDendpointの参照先同名tableの誤指定を見つける
field ID / name更新fieldLinked record型かschemaと比較
payload shapestring, object, array公式field data typeと照合

単にstatus codeだけで判断しないでください。API responseはJSONのerror/messageを含み、base固有のvalidationが422になることがあります。本文、URL、PAT、個人情報を含むpayloadを公開issueへ貼らず、必要ならtokenを除いて安全なsupport channelへ提供します。

field typeとpayloadを照合する

Airtableの公式Supported field types一覧ではLinked recordのdata typeを「array of record IDs (strings)」と説明しています。従って、次のようにrecord IDの配列として表現します。


{

  "fields": {

    "Related records": ["recXXXXXXXXXXXXXX"]

  }

}

これは形式を示す例で、実在するBase、Table、Field、Record IDではありません。1つのrecordをリンクする場合も配列です。複数をリンクする場合は、許可されているrecord IDを同じ配列に並べます。空配列が「リンクを解除する」操作になるか等は、更新方式と意図を確認してから使い、未確認のまま既存関係を消さないでください。

次を比較します。

  1. APIへ送っているfield名またはfield IDが、対象base/tableのLinked record fieldを指すか。

  2. JSONでfield valueがarrayになっているか。

  3. 配列要素がrecord ID文字列か。表示名やオブジェクトそのものを誤って渡していないか。

  4. record IDがLinked recordの参照先tableに属するか。

  5. endpointのBase ID、Table ID、record IDが同じデータ構造を指すか。

  6. linked fieldの設定先が、想定したforeign tableか。

  7. request bodyが有効なJSONで、write requestに適切なContent-Typeを含むか。

IDの配列に直しても、参照先が違うtableなら成功しません。recordのprimary fieldに見える名前やdisplay valueはrecord IDではありません。API responseやmetadataから実IDと参照先を照合してください。

参照先recordが見つからない場合

リンク先のrecord IDがそのLinked record fieldのforeign tableに存在するか確認します。誤ったbaseやtableのIDを混ぜていないか、recordが削除済みでないかも見ます。Airtable公式troubleshootingによると、新しいlinked-record valueに一致するrecordをforeign tableで見つけられないと、APIはその値をprimary fieldとするforeign recordを作成しようとすることがあります。これは単純な「record IDを一つ新規作成する」処理と同義ではないため、意図しないrecord作成が起こらないよう既存IDを確認してください。

同資料は、そのforeign tableがsynced tableの場合はrecord作成ができず、primary fieldがformulaの場合も直接書き込めないため、その作成要求は失敗すると説明しています。この制約の例は公式資料上403 invalid_permissionsとして記載されるため、これをHTTP 422の一般的な原因と表現してはいけません。422が返ったなら、まずそのstatusとerror bodyに記載されたvalidationを追い、403等が返った場合にforeign table作成制約や権限を確認します。

表は横にスクロールできます

返された状態最初に調べること次の操作
422 + field/type errorJSON型、array構造、field schema、値の形式最小payloadにしてfield単位で再試験
422 + invalid request bodyJSON構文、endpoint、Content-Type、field名JSONとAPI operation exampleを照合
403 invalid_permissionstoken/base access、table/field permissionAPIとUIの操作可能性を比較
403 linked record writeforeign tableにrecordを作る必要があるかsynced table/formula primaryの制約を確認
404 / record not foundBase/Table/record ID、削除・参照先正しいforeign tableのIDか照合

最小payloadで再試験する

本番の複数field更新を何度も繰り返さず、許可されたtest recordと既存foreign recordを使って、Linked record field一つだけを更新します。まず既存record IDを一つ配列で送り、status、error body、readbackされたlink IDを記録します。成功したら必要な件数を段階的に増やします。fieldを空配列にする、参照先の新recordを作るなど既存データへ影響する操作は、対象と結果を明確にしてから実行します。

作業前に送信payloadを小さくし、変更する一項目を決めます。配列の形と参照先IDを同時に変更すると、成功・失敗の理由を区別できません。Test baseを使えない場合は、既存の非重要recordや複製環境が利用できるか所有者へ確認し、production dataに対して試験書き込みをしないでください。

回帰確認では以下を見ます。

  • Linked record field valueがstring[]形式になっている。

  • 既存foreign record IDを参照している。

  • Readbackのlinked record IDsが期待した件数と一致する。

  • 無関係なfield、既存link、recordを変更していない。

  • 422と403をerror type/messageで別々に記録している。

  • requestを再送しても意図しないforeign record作成が起きない。

field/table権限とAPI errorを分離する

正しい配列でも書込みできない場合は、tokenがbase/tableへアクセスできるか、対象fieldまたはtableで編集権限が制限されていないか確認します。Airtable API troubleshootingは403 invalid_permissionsを、tokenが正しく渡されたがAPI操作の権限がない状態として説明し、field/table-level permissionも調べるよう案内しています。UIで同じ操作を試すことで、permission restrictionのfieldを絞る方法も紹介されています。

423など別のstatusやerror codeが出た場合は、その実レスポンスを使って追加調査します。エラー文に「422」と書かれていても、HTTP status field、error.type、messageが一致しているかを確認してください。HTTP 422は一般的な分類、Airtable error typeは個別の理由を示すため、異なるエラーを一つの原因へまとめないことが大切です。

送信前チェックリスト

  • statusとJSON error.type/messageを読んだ

  • endpointのBase ID / Table IDが対象base/tableを指す

  • fieldがLinked record型である

  • field valueがrecord ID文字列の配列である

  • record IDが参照先foreign tableの既存recordに属する

  • 同名だが別base/tableのrecordを使っていない

  • foreign tableの作成が発生する場合、synced/formula primary等の制約を調べた

  • token scope/base accessとfield/table editing permissionを確認した

  • 最小payloadのtestまたは非重要recordを使った

  • 更新後にlink IDと件数をreadbackした

  • PATやrecord本文をログへ出していない

次に行うこと

最初にAPI responseからHTTP status、error.type、message、対象fieldを控えます。field schemaのLinked record型と比較し、payloadをrecord ID文字列の配列へ整えます。そのIDが正しいforeign tableの既存recordか調べ、1件だけの最小更新を安全な環境で試します。422ならbody/schema/valueの具体的なvalidationを確認し、403ならtoken・field/table permissionとforeign record作成制約を確認してください。更新が成功したらlink IDを読み戻し、意図した一件だけが関連付いたことを確かめます。

このガイドでは特定baseのschema、PAT、record、権限を確認していません。Linked-record fieldの現行仕様とHTTP errorの適用条件は公式資料を優先し、特定の環境での原因はerror bodyとreadbackで確定してください。

Sources