Erreurs

Dernière mise à jour July 28, 2026

Chaque erreur partage une même enveloppe JSON, de sorte que vous pouvez les gérer de façon uniforme :

JSON

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

type — un code stable, lisible par machine (décidez selon ce champ, pas selon message).
message — une explication lisible par un humain.
request_id — la même valeur que l'en-tête de réponse X-Request-Id ; citez-la au support.

Types d'erreur

Statut	`type`	Quand cela se produit
400	`invalid_request`	Un paramètre requis est manquant ou mal formé (p. ex. un `q` vide).
401	`unauthorized`	Pas de clé d'API, ou une clé invalide / révoquée.
403	`insufficient_scope`	La clé existe mais n'a pas la portée `search` requise par l'endpoint.
402	`payment_required`	Pas d'abonnement Suede actif.
402	`insufficient_credits`	Votre solde de crédit d'API est vide. Achetez du crédit ou activez la recharge automatique.
429	`rate_limited`	Vous avez dépassé la limite de débit. Consultez Limites de débit.

En-têtes liés à la facturation

Un endpoint facturé au crédit renvoie aussi votre solde à chaque réponse, y compris les réponses d'erreur ci-dessus :

En-tête	Signification
`X-Credits-Balance`	Solde de crédit restant, en unités monétaires mineures (p. ex. centimes).
`X-Credits-Requests-Remaining`	Nombre approximatif de requêtes supplémentaires que ce solde couvre.
`X-Credits-Currency`	Code ISO en minuscules dans lequel le solde est libellé (les unités mineures suivent cette devise ; les devises sans décimales ne sont pas ×100).

Lire les erreurs

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