رموز الأخطاء

غلاف الخطأ

تعيد واجهة REST API كلّ خطأ على هيئة كائن JSON صغير يحتوي على حقلين: حقل code ثابت يمكنك بناء منطقك عليه، وحقل message مقروء للبشر. وتترجم البوابة الأخطاء الشائعة إلى إرشادات واضحة للمستخدم، لذلك نادراً ما ترى البيانات الخام في لوحة التحكم.

{
  "code": "BAD_IMAGE",
  "message": "image must use an immutable tag from an approved source"
}

رموز الحالة

تستخدم الأخطاء رمز حالة HTTP إضافةً إلى حقل code الموضّح أعلاه.

• 400 (فشل التحقّق من بيانات الطلب). رُفِضت قيم حزمة Docker أو الاسم أو الموارد أو المنطقة: BAD_JSON، BAD_NAME، BAD_RESOURCES، BAD_IMAGE، BAD_REGION. تُرفَض حزمة Docker هنا، وليس عبر 422، حين لا تحمل وسماً ثابتاً (لا تستخدم :latest أبداً) أو حين لا تأتي من المستودع الخاص بالمنصّة أو من حزمة أساس (base) مُعتمَدة. ويعني BAD_REGION أن رمز منطقة المشروع مفقود أو غير معروف — اختر واحداً من GET /v1/regions.
• 401 UNAUTHORIZED. رمز الوصول مفقود أو منتهي الصلاحية أو غير صالح.
• 402 INSUFFICIENT_BALANCE (اشحن رصيدك بقسيمة) أو ACCOUNT_NOT_INITIALIZED.
• 403 FORBIDDEN (لا تملك صلاحية التصرّف بهذا المورد) أو ACCOUNT_SUSPENDED.
• 404 NOT_FOUND. المورد غير موجود، أو ليس مملوكاً لك. حفاظاً على الخصوصية لا نوضّح أيّ الحالتين.
• 409 (تعارض مع الحالة الحالية). أمثلة: رمز *_TAKEN حين يكون الاسم مُستخدَماً من قبل، أو AUTOSCALING_OWNS_REPLICAS حين يكون عدد النسخ مُداراً بالتوسيع التلقائي ولا يمكن ضبطه يدوياً، أو LIFECYCLE_UNSUPPORTED، أو REGION_SERVICE_UNAVAILABLE حين لا تكون الخدمة متوفّرة بعد في منطقة مشروعك.
• 422 INSUFFICIENT_BALANCE_FOR_AUTOSCALING (الرصيد غير كافٍ لرفع الحدّ الأقصى لعدد النسخ)، أو NO_EMAIL (سياسة التنبيه تحتاج إلى بريد إلكتروني مُتحقَّق منه أولاً)، أو REGION_UNAVAILABLE (المنطقة التي اخترتها حقيقية لكنها ليست مفتوحة بعد — اختر منطقة متاحة أو انضمّ إلى قائمة انتظارها).
• 429 RATE_LIMITED. أنت ترسل الطلبات بسرعة كبيرة. انتظر قليلاً ثم أعِد المحاولة.
• 503 (ميزة مُعطَّلة أو غير متاحة مؤقتاً): AI_DISABLED، STRIPE_DISABLED، DB_BACKUP_UNAVAILABLE، REGISTRY_UNAVAILABLE.