الأخطاء
يتشارك كلّ خطأ غلاف 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 -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()}"); }
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})`); }