رموز الأخطاء واستكشاف الأعطال

الهيكل الموحد لأخطاء HTTP، ودليل رموز الاستجابة، وإرشادات المرونة.

في حال تعذر إكمال الطلب بنجاح، تعيد منصة SmallPict رمز حالة HTTP القياسي مصحوباً بكائن JSON مفصل لتسريع عملية تصحيح الأخطاء.

هيكل كائن الخطأ في JSON

JSON

{  "success": false,  "error": {    "code": "INVALID_IMAGE_PAYLOAD",    "message": "الملف المرسل ليس صورة صالحة أو أنه ملف تالف.",    "details": {      "mime_type": "text/html",      "expected": [        "image/jpeg",        "image/png",        "image/webp",        "image/avif"      ]    }  }}

جدول رموز أخطاء HTTP

الرمز	المعرف	السبب	الحل الموصى به
`400`	`BAD_REQUEST`	هيكل JSON غير صالح أو معاملات خاطئة.	تأكد من صحة تنسيق JSON وأسماء الحقول.
`401`	`UNAUTHORIZED`	مفتاح واجهة البرمجة مفقود أو تم إلغاؤه.	تأكد من ترويسة `X-API-Key`.
`401`	`TIMESTAMP_DRIFT`	انحراف الطابع الزمني بأكثر من ±300 ثانية.	قم بمزامنة ساعة الخادم عبر بروتوكول NTP.
`401`	`INVALID_SIGNATURE`	التوقيع الرقمي المحسوب غير متطابق.	راجع السلسلة المعيارية ومفتاح Secret Key.
`403`	`FORBIDDEN`	المفتاح لا يمتلك الصلاحية لهذا المورد.	اضبط صلاحيات المفتاح من لوحة التحكم.
`404`	`NOT_FOUND`	المهمة (`job_id`) أو الملف غير موجود.	تحقق من المعرف المدخل في الرابط.
`413`	`PAYLOAD_TOO_LARGE`	حجم الملف يتجاوز الحد الأقصى لخطتك.	قلص حجم الملف قبل الشروع في رفعه.
`415`	`UNSUPPORTED_MEDIA`	نوع وسائط غير مدعوم بواسطة المحرك.	أرسل ملفات JPEG, PNG, WebP, AVIF أو SVG فقط.
`422`	`UNPROCESSABLE`	امتداد الملف صحيح لكن محتواه تالف برمجياً.	تأكد من اكتمال رفع البيانات دون انقطاع.
`429`	`RATE_LIMIT_EXCEEDED`	تم تجاوز عدد الطلبات المسموح بها في الثانية.	طبق استراتيجية التراجع الأسي في المحاولات.
`429`	`QUOTA_EXCEEDED`	استنفاد الحصة الشهرية للتحويلات بالكامل.	قم بترقية باقة اشتراكك عبر لوحة التحكم.
`500`	`INTERNAL_ERROR`	خطأ غير متوقع في خوادم المعالجة السحابية.	أعد محاولة إرسال الطلب بعد فترة وجيزة.
`503`	`SERVICE_UNAVAILABLE`	صيانة مجدولة أو عبء مؤقت على المنصة.	اعتمد مؤقتاً على وضع passthrough.