Contents
概要
このドキュメントは、Salesforce の API 呼び出しで頻出するエラーコードの意味と、2026 年に導入された最新認証方式・設定手順を体系的にまとめたものです。エラーハンドリングだけでなく、MFA 環境下でも安定して接続できるようにチェックリストと実装例も提供します。
エラーコード別対処ガイド
ECONNRESET – 接続が強制切断された場合の基本確認
ECONNRESET はサーバー側が通信を途中で閉じたことを示すネットワークエラーです。主な原因はプロキシ設定ミス、ファイアウォールによるブロック、TLS バージョン不一致などです。
- プロキシと TLS の確認
- 環境変数
HTTPS_PROXYが正しく設定されているか確認（例:https://proxy.company.com:8080）。 -
使用している CLI が TLS 1.2 以上を要求することを保証。
-
実装手順
|
1 2 3 4 5 6 |
# 現在のプロキシ設定を表示 (Unix/macOS) echo $HTTPS_PROXY # 正しい値に上書き export HTTPS_PROXY=https://proxy.company.com:8080 |
設定後、以下コマンドでエラーが解消すれば完了です。
|
1 2 |
sfdx force:data:soql:query -q "SELECT Id FROM Account LIMIT 1" |
DomainNotFoundError – DNS 解決失敗の原因と対策
このエラーは指定したインスタンスドメインが名前解決できなかったことを示します。誤った loginUrl、サンドボックス URL の混在、カスタムドメイン削除が典型的です。
- URL 整合性のチェック
- 本番環境は
https://login.salesforce.com、Sandbox はhttps://test.salesforce.comを使用。 -
sfdx force:org:display -u <alias>で現在設定されているinstanceUrlを取得し、実際の組織と照合する。 -
修正例
|
1 2 3 |
# 正しいインスタンス URL に更新 sfdx force:config:set instanceurl=https://login.salesforce.com -u myOrgAlias |
OAUTH_APPROVAL_ERROR_GENERIC – 認可失敗の共通パターン
このコードは OAuth フロー中に何らかの承認エラーが起きたことを示します。主な要因は Connected App のスコープ不足、リダイレクト URI 不一致、ユーザーによる許可取り消しです。
- Connected App の必須設定
- スコープに
Refresh Token（offline_access）とAPI (api)を必ず含める。 -
リダイレクト URI が実際のエンドポイントと完全一致しているか確認する。
-
再認可手順
|
1 2 3 4 5 6 |
# 認証情報をクリア sfdx force:auth:logout -u myOrgAlias # 再ログイン（MFA 対応） sfdx auth:web:login -a myOrgAlias --instanceurl https://login.salesforce.com |
2026 年版最新認証方式と設定ポイント
OAuth 2.0 Authorization Code Flow with PKCE の活用
PKCE（Proof Key for Code Exchange）はモバイル・CLI 環境で MFA を回避しつつ安全にトークンを取得できるフローです。2026 年以降、Salesforce は標準的な auth:web:login に PKCE オプションを追加しました。
- 導入手順
- Connected App の「Enable OAuth Settings」画面で Require PKCE を有効化。
- CLI 実行時に
--usepkceフラグを付与するだけです。
|
1 2 |
sfdx auth:web:login -a myOrgAlias --instanceurl https://login.salesforce.com --usepkce |
ブラウザで表示された認可画面でユーザーが一度だけ MFA を完了すれば、以降はコードチャレンジが自動的に検証されます。
強化版 JWT Bearer Token（RSA‑PSS）フロー
2025 年に導入された RSA‑PSS 署名方式は従来の RSA‑SHA256 よりも高いセキュリティを提供します。証明書の生成からトークン取得までの流れは変わらず、署名アルゴリズムだけ PS256 に変更すれば利用できます。
- 実装例（Node.js）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
const jwt = require('jsonwebtoken'); const fs = require('fs'); const privateKey = fs.readFileSync('./server.key'); // RSA‑PSS 用秘密鍵 const payload = { iss: '<ConsumerKey>', sub: 'api_user@example.com', aud: 'https://login.salesforce.com', exp: Math.floor(Date.now() / 1000) + 300 // 有効期限は5分 }; const token = jwt.sign(payload, privateKey, { algorithm: 'PS256' }); await fetch('https://login.salesforce.com/services/oauth2/token', { method: 'POST', headers: {'Content-Type': 'application/x-www-form-urlencoded'}, body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion : token }) }); |
取得したアクセストークンは従来通り REST / SOAP API の Authorization ヘッダーに使用できます。
Device Authorization Flow（デバイスコードフロー）の実務活用
CLI が端末コードを表示し、ユーザーはブラウザで認可ページにアクセスして MFA を完了する方式です。2026 年の CLI バージョン vX.Y では次のように利用できます。
|
1 2 3 |
sfdx auth:device:login -a myOrgAlias --instanceurl https://login.salesforce.com # => 表示されたコードをブラウザで入力し、MFA を完了 |
デバイス側はトークン取得まで待機するだけなので、スクリプト化が容易です。
Connected App のベストプラクティス（2026 年版）
必須設定項目とチェックリスト
| 項目 | 推奨設定例 | コメント |
|---|---|---|
| OAuth スコープ | api, offline_access, refresh_token |
最小権限の原則に従い必要なものだけ付与 |
| リダイレクト URI | https://myapp.example.com/callback（正確に一致） |
末尾のスラッシュは含めない |
| PKCE 要求 | 有効 | モバイル・CLI 環境で必須 |
| 証明書タイプ | RSA‑PSS (PS256) | 高セキュリティ要件がある場合に選択 |
| IP Relaxation ポリシー | Relaxed（プロキシ経由のアクセスが必要なとき） |
必要に応じて設定 |
権限付与手順（Permission Set 推奨）
- Permission Set 作成
- 「API Enabled」チェックボックスをオン。
-
「Connected App Access」に対象の Connected App を選択。
-
ユーザーへ割り当て
|
1 2 |
sfdx force:user:permset:assign -n API_Access_Set -u myOrgAlias |
- 設定が反映されたことを
force:org:displayで確認します。
トラブルシューティングチェックリスト（実装例）
以下はインシデント対応時にマークダウン形式のチェックボックスで管理できるよう設計しました。完了したら [x] に置き換えてください。
- [ ] エラーメッセージ取得
-
Debug Log または Event Monitoring から該当コード（例：ECONNRESET、DomainNotFoundError）を抽出
-
[ ] 接続先 URL の整合性確認
-
sfdx force:org:display -u <alias>でinstanceUrlが組織と一致しているか検証 -
[ ] プロキシ・TLS 設定の見直し
-
環境変数
HTTPS_PROXYが正しいか、TLS バージョンが 1.2 以上か確認 -
[ ] Connected App のスコープとリダイレクト URI を検証
-
api,offline_accessが有効か、PKCE が有効化されているかチェック -
[ ] 認証方式の選択・実装
-
PKCE, JWT‑PS256, または Device Flow のうち最適なものを使用しているか確認
-
[ ] ユーザー権限の再付与
-
Permission Set に「API Enabled」および Connected App アクセスが含まれていることを確認
-
[ ] 再実行テスト
- 修正後に同一 API リクエスト（例：
sfdx force:data:soql:query -q "SELECT Id FROM Account LIMIT 1"）で成功するか検証
復旧フロー
- 確認 – ログ取得とエラーコード特定
- 修正 – URL・プロキシ・Connected App 設定・権限のいずれかを更新
- 再検証 – 同一リクエストで成功、チェックリスト全項目に ✅ を付与
まとめ
本稿では代表的な API エラーコードと対処法、2026 年版の最新認証フロー（PKCE、RSA‑PSS JWT、Device Flow）、Connected App のベストプラクティス、そして実務ですぐに使えるチェックリストを網羅しました。エラーログ取得から設定修正・再テストまで一貫した手順を踏むことで、MFA 環境下でも安定的な Salesforce API 接続が実現できます。