エラー

すべてのエンドポイントのすべてのエラーは、1つの外枠を使います。

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

error.codeで分岐し、人にはerror.messageを表示してください。検証エラーには、フィールド ごとのメッセージを持つdetails配列が加わります。

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

エラーコード

| コード | HTTP | 意味 | 対処 | |---|---|---|---| | unauthorized | 401 | キーが未指定、未知、失効済み、または期限切れ | ヘッダーを確認する。新しいキーを発行する | | forbidden | 403 | エンドポイントに対してキーの種類が違う、またはその操作が許可されていない | ドキュメントどおりにワークスペースキー / パートナーキーを使う | | insufficient_scope | 403 | 必要なスコープをキーが持っていない | メッセージに示されたスコープを持つキーを作成する | | plan_restricted | 403 | この機能はプランに含まれていない | プランをアップグレードするか、その機能をリクエストから外す | | not_found | 404 | リソースが存在しない、または別のテナントに属している | idを確認する。他人のリソースは、存在しないものと区別できない | | invalid_request | 400 | 不正なJSON、壊れたカーソル、業務ルール違反 | リクエストを修正する | | validation_failed | 422 | 本文またはクエリがスキーマ検証に失敗した | detailsに列挙されたフィールドを修正する | | conflict | 409 | 状態の衝突。使用済みのスラッグ、本文の異なるIdempotency-Keyの再利用など | 別の値か、新しい冪等キーを選ぶ | | quota_exceeded | 422 | プランの割り当てを使い切った（リンク、ドメイン、クライアント） | プランをアップグレードするか、割り当てを空ける | | rate_limited | 429 | このキーからのリクエストが多すぎる | Retry-After秒だけ待つ。レート制限を参照 | | not_configured | 503 | この環境ではその機能が設定されていない | 後で再試行するか、サポートへ連絡する | | internal | 500/502/504 | プラットフォーム側の想定外のエラー | バックオフを入れて再試行し、続くようなら報告する | | invalid_click_id | 422 | click_idが偽造または改ざんされている、あるいは別のワークスペースで発行された | クリックの識別子のパラメータの値を、リンク先のアドレスにあったとおりにそのまま渡す | | attribution_expired | 422 | クリックがワークスペースのアトリビューション期間より古い | 再試行する意味はない。必要ならダッシュボードで期間を調整する |

効いてくる処理の原則

• 404は分離の仕組みでもあります。 別のワークスペースのidにはforbiddenではなく必ず not_foundが返ります。APIは、他人のidが存在するかどうかを明かしません。
• 安全なものだけ再試行してください。 internalとrate_limitedはバックオフを入れて 再試行します。conflictやvalidation_failedをむやみに再試行してはいけません。リクエスト 自体が誤っているからです。更新系の再試行を安全にするにはIdempotency-Keyを使ってください。
• GET /linksが404を返すことはありません。 条件に何も当てはまらない場合は空の一覧が 返ります。コレクションに対する404は、意味が曖昧になるからです。