エラー

最終更新 July 28, 2026

すべてのエラーはひとつの JSON エンベロープを共有するため、統一的に扱える:

JSON

{
  "error": {
    "type": "invalid_request",
    "message": "Query parameter 'q' is required.",
    "request_id": "a1b2c3d4e5f6a7b8"
  }
}

type — 安定した、機械可読なコード(message ではなく、これで分岐すること)。
message — 人間が読める説明。
request_id — X-Request-Id レスポンスヘッダーと同じ値。サポートに引用すること。

エラーの型

ステータス	`type`	発生する状況
400	`invalid_request`	必須パラメータが欠落しているか、不正な形式である(例えば空の `q`)。
401	`unauthorized`	API キーがない、または無効 / 失効したキー。
403	`insufficient_scope`	キーは存在するが、エンドポイントが要求する `search` スコープを欠く。
402	`payment_required`	有効な Suede メンバーシップがない。
402	`insufficient_credits`	API クレジット残高が空である。クレジットを購入するか、自動リロードを有効にすること。
429	`rate_limited`	レート制限を超えた。レート制限を参照のこと。

課金に関するヘッダー

クレジットで課金されるエンドポイントは、上記のエラーレスポンスを含め、すべてのレスポンスで残高も返す:

ヘッダー	意味
`X-Credits-Balance`	残っているクレジット残高。通貨の補助単位(例えばセント)で表す。
`X-Credits-Requests-Remaining`	その残高でまかなえる、おおよその追加リクエスト数。
`X-Credits-Currency`	残高の通貨を示す小文字の ISO コード(最小単位はこの通貨に従う。小数のない通貨は 100 倍しない)。

エラーの読み取り

cURL

curl -s "https://api.suede.io/v1/search" \
  -H "Authorization: Bearer $SUEDE_API_KEY"
# => HTTP 400  {"error":{"type":"invalid_request","message":"Query parameter 'q' is required.","request_id":"…"}}

using System.Text.Json;
var res = await http.GetAsync("https://api.suede.io/v1/search"); // missing q
if (!res.IsSuccessStatusCode)
{
    using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
    var err = doc.RootElement.GetProperty("error");
    Console.WriteLine($"{(int)res.StatusCode} {err.GetProperty("type").GetString()}: {err.GetProperty("message").GetString()}");
}

JavaScript

const res = await fetch("https://api.suede.io/v1/search", {
  headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` },
});
if (!res.ok) {
  const { error } = await res.json();
  console.error(`${res.status} ${error.type}: ${error.message} (request ${error.request_id})`);
}