Suede
في هذه الصفحة

الأخطاء

يتشارك كلّ خطأ غلاف 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":"…"}}
C#
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})`);
}
هل كانت هذه الصفحة مفيدة؟