トレントギア

スタートアップ時の5つの重要なAPI統合エラー

エラー#1。孤独と退却の「嵐」はありません

症状：注文/支払いの重複、金額の不一致、紛争リターン、DLQアラートが増加しています。

ルート：リクエスト/webhookとネットワークフラップの繰り返し配信は正常です。「create/write off」操作がidempotentでない場合、retraysはダメージを掛けます。

どのように

Idempotency-Key/' operation_id'はすべての安全でないメソッド（POST/PATCH）に適用されます。

'operation_id'のデータベース内の一意のインデックス。「再生」（Replay）-前の結果を返します。

受信トレイテーブルを介してWebhook （'event_id+signature'で削除）。アウトバウンドイベント-アウトボックス。

レトライ：最大1-2回、指数+ジッタ、安全な操作のためにのみ。

HTTP規約（例）：

http： http
POST/v1/支払い
Idempotency-Key： ik_f35a2
Content-Type： application/json

{「amount'： 5000、」 currency「：」EUR「、」source「：」card_..."}

SQL保護（簡略化）：

SQL
ALTER TABLE PAYMENTS ADD CONSTRAINT uniq_op UNIQUE （operation_id)；

ジッタ付きレトライ（擬似コード）：

python for i in range （2）：
try： return call_api（ペイロード、タイムアウト=0。6)
タイムアウト以外：
sleep （0。05 2i+ランダム。uniform （0、0。05))
アップストリームを上げる利用不可

チェックリスト：

すべての「monetary/creating」ロジックには'operation_id'とuniqインデックスがあります。
Inbound WebhookはInbox経由でのみidempotent workerを使用します。
クライアントSDKは自動的にIdempotency-Keyを設定します。

エラー番号2。タイムアウト/リトレイとSLO： 依存性の過熱

症状：P95が突然離れて浮いて、キューが成長し、サーキットブレーカー「前髪」。

ルート：レスポンスの合計SLOは400-600ミリ秒で、外部APIへのタイムアウトは1-2秒であり、3 ×の再トレイもあります。あなたはできるよりも長いことをし、繰り返しで中毒を襲います。

どのように

予算のタイミング：SLOが400 msの場合、アップストリームのタイムアウト：250-300 ms；SLO ≤リクエストの合計タイムアウト。

Limits/Backpressure：各依存関係への呼び出しのセマフォー/ワーカープール。混雑→一度に429/503。

サーキットブレーカ：タイムアウト/5xxで'open'、 'half-open'投与。

入場管理：並行性を制限します（スレッドごと、エンドポイントごと/PSP）。

例（Go）：

go sem：=make （chan struct{}、64 ）//competition limit to PSP func callPSP （ctx context。Context、 req Req） （Res、 error）{
選択してください{
case sem<-struct{}{}：
func（）{<-sem}（）
c、 cancel：=context。WithTimeout （ctx、 300時間。ミリ秒）
defer cancel（）
PSPを返します。Do （c、 req）
デフォルト：
Res{}を返します。ErrBusy//endless queueではなくimmediate failure
}
}

チェックリスト：

タイムアウトはSLOより短い；レトライ≤ 2；ジッタがある。
外部APIへのプール/セマフォー；メトリクスが付いている遮断器。
忙しいルートでは、接続を維持しないで、429/Retry-Afterを返します。

エラー番号3。弱いセキュリティ： Webhook署名、秘密、TLS

症状：「他人の」webhookパス、コード/ログの秘密、MITMリスク。

ルート：署名/新鮮さチェックなし、秘密はenvファイル、古いTLS、弱いヘッダーに住んでいます。

どのように

Webhookの署名HMAC-SHA256+'X-Timestamp'（ウィンドウ≤ 5-10分）、署名の厳密な比較。

重要な統合またはIP allow-listのためのmTLS。

Vault/Cloud KMSによる秘密の回転;最小限の権利；減算監査。

TLS 1。2/1.3のみ、HSTS、正しいCORS（狭いソースリスト）。

署名検証（Python）：

python def verify （sig_hdr、 ts_hdr、 body、 secret）：
abs（時間。time（）-int （ts_hdr)）> 600： raise Expired（）
calc=hmac。new （secret、 （ts_hdr+「」。+body）。encode（）、hashlib。sha256）。hexdigest（）
HMACじゃないなら。compare_digest （calc、 sig_hdr)： raise BadSig（）

チェックリスト：

すべてのWebhookは署名され、確認されます；新鮮さの窓は限られています。
KMS/Vaultの秘密、回転と監査があります。
TLS/HSTSが有効になっています。CORSポイント；IP/mTLSが適切な場合。

エラー番号4。契約ドリフト： スキーム「その人生を生きた」

症状：prodは「一部のクライアントでのみ」、ログでは500/422、 SDKとAPIの異なるバージョンが主張します。

ルート：契約の厳密な説明、後方互換性のない変更、「静かな」フィールド、同じ名前の異なる意味はありません。

どのように

Contract-first： OpenAPI/AsyncAPI+サーバ/クライアント生成；イベント-Avro/Protobuf+Schema Registry。

バージョン管理：'v1→v2' （URI/ヘッダ）、 deviation-plan、 grace-period。

後方コンパット：マイナーリリースの追加変更のみ。v-bumpなしで削除/名前変更することはできません。

契約テスト：Pact/Buf-プロバイダ/コンサマーはCIでテストされます。

例：

yaml
OpenAPI：マイナーなamount_minor単位の和の明確なタイプ：
type：整数最小：0説明：最小通貨単位の合計（整数）

チェックリスト：

コントラクトはgitに格納され、CIは互換性がない場合に検証/破断します。
イベントのスキーマレジスタ、「back/forward」互換性。
変更のドッキングページ、退役の日付、パートナーのためのテストベンチ。

エラー番号5。「ブラインド」起動： メトリック/ログ/トレイルおよびサンドボックスなし

症状：「何も表示されません」、サポートが満ち、debag-prodの手。

ルート：観察可能性は含まれていませんでした、合成はありません、サンドボックスは「言葉で」テストされました。

どのように

RED/USEメトリクス：各エンドポイントのrate/error/latencyをroute/methodで指定します。

相関：すべてのログとレスポンスの'trace_id'；zapros↔vebkhukの束。

合成：健康検査（ログイン/預金砂）、Webhook用のSLA監視T+60。

サンドボックス/ステージ：完全に分離されたキー/ドメイン、架空のPSP、「レポートに含まれていない」エントリ。

トレースIDによる応答：

http： http
 。 。1 202受け入れられました
トレースID： 7f2b3d8e9c1a4
ロケーション：/v1/ops/req_42/status

チェックリスト：

RED/USEメトリック、ダッシュボード、アラート（症状+原因）。
エンドツーエンドのトレイル；JSONログ、no PII、 'trace_id'。
主要地域からの合成；サンドボックスが必要です、異なるキー。

プレランチプラン（T-7→T-0）

T-7日：

最終契約スキャン：互換性のない変更はありますか？フリーズスキーム。
秘密/証明書：ローテーション、アクセス、KMSポリシーをチェックします。
Synthetics 24 × 7、アラートはオンコールに関連付けられています。

T-3日：

ミニランの読み込み（バースト2-5分）：グリーンゾーンのp95/プール/キュー。
DRY-RUN Webhooks（リプレイ、5xx、ジッタ）、DLQチェック。
パートナーの「電話帳」：L1/L2の連絡先、戦争部屋チャンネル。

T-0：

チャネル交通SLOのゲートのための5％→25％→50％；準備ができたロールバック。
危険な機能のキルスイッチ/フィーチャーフラグが含まれています。
ウォールルームはアクティブで、ステータステンプレートが用意されています。

ロールバック計画（何か問題があった場合）

1.以前の安定したバージョン/ルートにトラフィックを解放します。

2.phicheflag物議を醸す変更を無効にします。

3.キュー/プールを安定させ、嵐の中で後退を止める。

4.ポストインシデント：タイムライン、ルーツ、タスクを収集します（固定転送/契約の修正）。

セルフテストテーブルを開始する（短い）

［ブロック］	お問い合わせ	ええ、いいえ
Idemotence（アイデンポテ	すべての「作成」メソッドにはIdempotency-Key/' operation_id'とuniqインデックスがありますか？
リトレイ/タイムアウト	タイムアウトはSLOより短いです。レトライ≤ 2；ジッタ・オン？
安全性について	Webhooks署名、新鮮さの窓≤ 10分、KMSの秘密？
プライバシーポリシー	OpenAPI/AsyncAPIが修正され、CIは非互換性をキャッチしますか？
Observability（可視性）	RED/USE、トレイル、合成T+60、サンドボックス分離？
ロールバック（Rollback）	/kill-switchロールバックボタン、通信プランはありますか？

よくある質問「what if……」

...プロバイダはIdempotency-Keyをサポートしていませんか？

'hash （body）'+'partner_request_id'を保存し、idempotencyを入力します。

...webhookは時々答えを「前に」来るか？

'operation_id'を縫い、一時的に「unknown→reconcile」ステータスを保持します。定期的な和解は矛盾を閉じるでしょう。

...古い顧客と新しいをサポートする必要がありますか？

ヘッダ/URIによるルートであるエンドポイント（'/v1'および'/v2'）をバージョン化すると、少なくともNヶ月間は下位互換性が維持されます。

履歴書のサマリー

統合の失敗はほぼ常に同じことです。idempotency、間違ったタイムアウトとリトリート、Webhookの弱い署名、契約のドリフト、可視性の欠如。事前に契約を修正し、可視性を有効にし、限界/バックプレッシャーを配置し、すべての外部インタラクションに署名し、合成を実行します。その後、パートナーの失敗の場合でも、あなたのリリースは管理可能なままになります-レトラで失われたお金なし、そしてチーム全体のための眠れない夜なし。