Erreurs et débogage

​

Exemple de réponse d’erreur

{
  "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
    }
  ]
}

​

Champs toujours présents

• generation_id : identifiant de requête stable que vous pouvez communiquer au support.
• status_code : correspond au code d’état HTTP.
• error : code lisible par machine, comme validation_error.
• error_type : catégorie générale, généralement user ou system.
• error_origin : indique si le problème provient principalement de l’appelant, de Phaseo ou d’un fournisseur en amont.
• description : explication claire de ce qui s’est passé.
• details (facultatif) : détails de validation structurés lorsque l’erreur concerne une requête invalide.

​

Autres champs possibles

• reason : sous-motif plus précis, comme all_candidates_failed ou pricing_not_configured.
• provider_candidate_diagnostics et provider_enablement : expliquent pourquoi un modèle n’a pas pu être utilisé avec le point de terminaison demandé.
• routing_diagnostics : précisions sur la manière dont le routage ou les contrôles de disponibilité ont réduit les options.
• provider_failure_diagnostics : indications concernant des identifiants manquants, un accès refusé, des restrictions régionales, des limites de débit ou d’autres échecs côté fournisseur.
• upstream_error et failure_sample : résumé au mieux du premier échec fournisseur, si la requête a atteint un fournisseur.
• failed_providers, failed_statuses et attempt_count : contexte supplémentaire sur les nouvelles tentatives et le basculement.

​

Interpréter les classes de statut

​

Codes d’erreur courants

​

En cas d’échec d’un fournisseur

• 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

​

Lorsqu’un modèle ou un point de terminaison est indisponible

• provider_candidate_diagnostics
• provider_enablement
• missing_pricing_providers
• routing_diagnostics

• un modèle connu qui n’est pas encore actif
• un modèle incompatible avec le point de terminaison demandé
• l’absence de données de tarification
• des restrictions de déploiement ou de disponibilité interne

• provider_candidate_diagnostics.totalProviders : nombre de fournisseurs connus pour le modèle avant le filtrage par point de terminaison.
• provider_candidate_diagnostics.supportsEndpointCount : nombre de ces fournisseurs prenant en charge le point de terminaison demandé.
• provider_candidate_diagnostics.candidateCount : nombre de fournisseurs restants après les vérifications de l’adaptateur.
• provider_candidate_diagnostics.droppedUnsupportedEndpoint : fournisseurs retirés parce qu’ils ne prennent pas en charge le point de terminaison.
• provider_candidate_diagnostics.droppedMissingAdapter : paires fournisseur/point de terminaison retirées parce qu’aucun adaptateur Gateway n’existe encore pour ce point de terminaison.
• provider_enablement.capability : capacité contrôlée, par exemple video_generation.
• provider_enablement.providersBefore / provider_enablement.providersAfter : fournisseurs avant et après le filtrage des capacités ou des activations.
• provider_enablement.dropped[].reason : motifs lisibles par machine, comme pricing_missing.
• routing_diagnostics.filterStages[].stage : étape de routage, comme le filtrage par capacité, déploiement ou état de routage.
• routing_diagnostics.filterStages[].beforeCount / routing_diagnostics.filterStages[].afterCount : nombre de fournisseurs avant et après chaque étape.
• routing_diagnostics.filterStages[].droppedProviders[].reason : motifs lisibles par machine, comme des restrictions de déploiement ou de routage.

​

Exemple

{
  "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"
          }
        ]
      }
    ]
  }
}

​

Mode de débogage facultatif

{
  "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 ou full)

​

Stratégie de nouvelle tentative

• Erreurs de la série 400 autres que 429 : corrigez la requête, les identifiants ou la politique d’accès avant de réessayer.
• 429 : appliquez un délai exponentiel et respectez l’en-tête Retry-After.
• Erreurs de la série 500 : utilisez des tentatives limitées uniquement lorsque répéter l’opération est sûr. Une soumission dont le résultat est incertain peut déjà avoir créé une tâche ou entraîné des frais ; récupérez une tâche acceptée au lieu de la soumettre à nouveau.

​

Particularités du streaming

• Si la requête échoue avant le début du streaming, vous recevez une réponse d’erreur JSON standard.
• Si elle échoue en cours de flux, considérez le flux partiel comme incomplet et proposez une nouvelle tentative.
• Enregistrez toujours generation_id ainsi que les métadonnées du point de terminaison et du modèle.

​

Conseils de dépannage

• Consultez la page d’état Gateway pour connaître les incidents en cours.
• Comparez le corps de votre requête avec la documentation du point de terminaison.
• Communiquez generation_id au support.

​

Ressources associées