الأخطاء وتصحيحها

​

مثال على استجابة خطأ

{
  "generation_id": "G-abc123",
  "status_code": 502,
  "error": "upstream_error",
  "error_type": "system",
  "error_origin": "upstream",
  "reason": "all_candidates_failed",
  "description": "Provider \"google-ai-studio\" failed with HTTP 403 for endpoint \"responses\" on model \"google/gemini-2.5-pro\".",
  "attempt_count": 1,
  "failed_providers": ["google-ai-studio"],
  "failed_statuses": [403],
  "provider_failure_diagnostics": {
    "category": "provider_access_missing",
    "hint": "The provider account appears not to have access to this model or feature yet. Verify account entitlements and provider-side access.",
    "provider": "google-ai-studio"
  },
  "upstream_error": {
    "code": "PERMISSION_DENIED",
    "message": "The caller does not have permission.",
    "description": null,
    "param": null
  },
  "failure_sample": [
    {
      "provider": "google-ai-studio",
      "type": "upstream_non_2xx",
      "status": 403,
      "upstream_error_code": "PERMISSION_DENIED",
      "upstream_error_message": "The caller does not have permission.",
      "upstream_error_description": null,
      "upstream_error_param": null,
      "upstream_payload_preview": "{\"error\":{\"status\":\"PERMISSION_DENIED\"}}",
      "retryable": false
    }
  ]
}

​

الحقول التي ستتلقاها دائمًا

• generation_id: معرّف طلب ثابت يمكنك مشاركته مع فريق الدعم.
• status_code: يطابق رمز حالة HTTP.
• error: رمز خطأ قابل للقراءة آليًا، مثل validation_error.
• error_type: فئة عامة، تكون عادةً user أو system.
• error_origin: يوضح ما إذا كان السبب الأساسي هو المتصل أو Phaseo أو مزوّد أساسي.
• description: شرح مبسط لما حدث.
• details (اختياري): تفاصيل تحقق منظمة عندما يكون الخطأ متعلقًا بالتحقق من صحة الطلب.

​

حقول إضافية قد تظهر

• reason: سبب فرعي أدق، مثل all_candidates_failed أو pricing_not_configured.
• provider_candidate_diagnostics وprovider_enablement: يوضحان سبب تعذر استخدام النموذج مع نقطة النهاية المطلوبة.
• routing_diagnostics: تفاصيل إضافية عن كيفية تضييق خيارات الطلب عبر فحوصات التوجيه أو التوفر.
• provider_failure_diagnostics: تلميحات بشأن بيانات الاعتماد المفقودة أو غياب الوصول أو القيود الإقليمية أو حدود المعدل وإخفاقات المزوّد المماثلة.
• upstream_error وfailure_sample: ملخص بأفضل جهد لإخفاق المزوّد الأول إذا وصل الطلب إلى مزوّد.
• failed_providers وfailed_statuses وattempt_count: سياق إضافي حول إعادة المحاولة والتحويل الاحتياطي.

​

إرشادات فئات الحالة

​

رموز الأخطاء الشائعة

​

عند إخفاق مزوّد

• provider_failure_diagnostics.category
• provider_failure_diagnostics.hint
• provider_failure_diagnostics.provider

• credentials_not_configured
• credentials_invalid_or_forbidden
• provider_access_missing
• region_or_project_restriction
• model_unavailable_for_endpoint
• rate_limited
• server_error

​

عند عدم توفر نموذج أو نقطة نهاية

• provider_candidate_diagnostics
• provider_enablement
• missing_pricing_providers
• routing_diagnostics

• نموذج معروف لم يُفعّل بعد
• نموذج لا يدعم نقطة النهاية المطلوبة
• بيانات أسعار مفقودة
• قيود الطرح أو التوفر الداخلي

• provider_candidate_diagnostics.totalProviders: عدد المزوّدين المعروفين للنموذج قبل التصفية حسب نقطة النهاية.
• provider_candidate_diagnostics.supportsEndpointCount: عدد المزوّدين الذين يدعمون نقطة النهاية المطلوبة.
• provider_candidate_diagnostics.candidateCount: عدد المزوّدين المتبقين بعد فحوصات المحوّل.
• provider_candidate_diagnostics.droppedUnsupportedEndpoint: المزوّدون المستبعدون لعدم دعم نقطة النهاية.
• provider_candidate_diagnostics.droppedMissingAdapter: أزواج المزوّد ونقطة النهاية المستبعدة لعدم وجود محوّل Gateway لهذه النقطة بعد.
• provider_enablement.capability: بوابة الإمكانية قيد التنفيذ، مثل video_generation.
• provider_enablement.providersBefore / provider_enablement.providersAfter: المزوّدون قبل التصفية حسب الإمكانية أو التفعيل وبعدها.
• provider_enablement.dropped[].reason: أسباب قابلة للقراءة آليًا، مثل pricing_missing.
• routing_diagnostics.filterStages[].stage: مرحلة التوجيه، مثل التصفية حسب الإمكانية أو الطرح أو حالة التوجيه.
• routing_diagnostics.filterStages[].beforeCount / routing_diagnostics.filterStages[].afterCount: عدد المزوّدين قبل كل مرحلة وبعدها.
• routing_diagnostics.filterStages[].droppedProviders[].reason: أسباب قابلة للقراءة آليًا، مثل قيود الطرح أو التوجيه.

​

مثال

{
  "generation_id": "G-unsupported123",
  "status_code": 400,
  "error": "unsupported_model_or_endpoint",
  "description": "No provider is currently routable for endpoint \"responses\" on model \"example/model\".",
  "provider_candidate_diagnostics": {
    "totalProviders": 3,
    "supportsEndpointCount": 2,
    "candidateCount": 1,
    "droppedUnsupportedEndpoint": ["provider-a"],
    "droppedMissingAdapter": [
      {
        "providerId": "provider-b",
        "endpoint": "responses"
      }
    ]
  },
  "provider_enablement": {
    "capability": "responses",
    "providersBefore": ["provider-b", "provider-c"],
    "providersAfter": ["provider-c"],
    "dropped": [
      {
        "providerId": "provider-b",
        "reason": "pricing_missing"
      }
    ]
  },
  "routing_diagnostics": {
    "filterStages": [
      {
        "stage": "provider_routing_status",
        "beforeCount": 1,
        "afterCount": 0,
        "droppedProviders": [
          {
            "providerId": "provider-c",
            "reason": "provider_status_not_ready"
          }
        ]
      }
    ]
  }
}

​

وضع تصحيح اختياري

{
  "debug": {
    "enabled": true,
    "return_upstream_request": true,
    "return_upstream_response": false,
    "trace": true,
    "trace_level": "summary"
  }
}

• enabled
• return_upstream_request
• return_upstream_response
• trace
• trace_level (summary أو full)

​

استراتيجية إعادة المحاولة

• أخطاء الفئة 400 باستثناء 429: صحّح الطلب أو بيانات الاعتماد أو سياسة الوصول قبل إعادة المحاولة.
• 429: طبّق تراجعًا أسيًا والتزم بترويسة Retry-After.
• أخطاء الفئة 500: استخدم إعادة المحاولة ضمن حدود فقط عندما يكون تكرار العملية آمنًا. قد يكون الإرسال ذو النتيجة غير المؤكدة قد أنشأ مهمة أو تسبب في رسوم بالفعل؛ استرجع المهمة المقبولة بدلًا من إرسالها مجددًا.

​

ملاحظات خاصة بالبث

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

​

نصائح لاستكشاف المشكلات

• تحقّق من صفحة حالة Gateway للاطلاع على الحوادث الجارية.
• راجع حمولة الطلب مقابل توثيق نقطة النهاية.
• شارك generation_id عند التواصل مع الدعم.

​

موارد ذات صلة