Fehler

Zuletzt aktualisiert July 28, 2026

Jeder Fehler teilt sich einen einzigen JSON-Umschlag, sodass Sie sie einheitlich behandeln können:

JSON

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

type — ein stabiler, maschinenlesbarer Code (entscheiden Sie danach, nicht nach message).
message — eine menschenlesbare Erläuterung.
request_id — derselbe Wert wie der X-Request-Id-Antwort-Header; nennen Sie ihn dem Support.

Fehlertypen

Status	`type`	Wann er auftritt
400	`invalid_request`	Ein erforderlicher Parameter fehlt oder ist fehlerhaft (z. B. ein leeres `q`).
401	`unauthorized`	Kein API-Schlüssel, oder ein ungültiger / widerrufener Schlüssel.
403	`insufficient_scope`	Der Schlüssel existiert, aber ihm fehlt der vom Endpunkt verlangte Geltungsbereich `search`.
402	`payment_required`	Keine aktive Suede-Mitgliedschaft.
402	`insufficient_credits`	Ihr API-Guthaben ist leer. Kaufen Sie Guthaben oder aktivieren Sie die automatische Aufladung.
429	`rate_limited`	Sie haben die Ratenbegrenzung überschritten. Siehe Ratenbegrenzungen.

Abrechnungsbezogene Header

Ein per Guthaben abgerechneter Endpunkt gibt Ihr Guthaben auch bei jeder Antwort zurück, einschließlich der Fehlerantworten oben:

Header	Bedeutung
`X-Credits-Balance`	Verbleibendes Guthaben, in kleineren Währungseinheiten (z. B. Cent).
`X-Credits-Requests-Remaining`	Ungefähre Anzahl weiterer Anfragen, die dieses Guthaben abdeckt.
`X-Credits-Currency`	Kleingeschriebener ISO-Code, in dem das Guthaben geführt wird (die kleinsten Einheiten folgen dieser Währung; Währungen ohne Dezimalstellen sind nicht ×100).

Fehler auslesen

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})`);
}