त्रुटियाँ और डीबगिंग

​

त्रुटि प्रतिक्रिया का उदाहरण

{
  "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: स्थिर request ID जिसे आप support के साथ साझा कर सकते हैं।
• 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)

​

पुनः प्रयास की रणनीति

• 429 को छोड़कर 400-श्रेणी की त्रुटियाँ: पुनः प्रयास से पहले अनुरोध, क्रेडेंशियल या पहुँच नीति ठीक करें।
• 429: Exponential backoff लागू करें और Retry-After header का पालन करें।
• 500-श्रेणी की त्रुटियाँ: सीमित पुनः प्रयास केवल तभी करें जब ऑपरेशन दोहराना सुरक्षित हो। अनिश्चित परिणाम वाले सबमिशन से जॉब बन चुका हो सकता है या शुल्क लग चुका हो सकता है; स्वीकार किए गए जॉब को दोबारा भेजने के बजाय उसकी जानकारी प्राप्त करें।

​

स्ट्रीमिंग के लिए खास बातें

• Streaming शुरू होने से पहले request विफल हो, तो standard JSON error payload मिलता है।
• Stream के बीच में विफलता हो, तो partial stream को अधूरा मानें और retry का विकल्प दें।
• हमेशा generation_id और endpoint/model metadata रिकॉर्ड करें।

​

समस्या हल करने के सुझाव

• चल रही घटनाओं के लिए Gateway status page देखें।
• Request payload को endpoint docs से मिलाकर देखें।
• Support से संपर्क करते समय generation_id साझा करें।

​

संबंधित संसाधन