Das Verständnis, wie die API Fehler meldet, hilft Ihnen, schnell zu reagieren und Ihre Integration widerstandsfähig zu halten. Die Fit It On API kategorisiert Fehler in zwei verschiedene Phasen:
- API-Ebene-Fehler: Die Anfrage wurde sofort abgelehnt, bevor eine Vorhersage-ID ausgestellt wurde.
- Laufzeitfehler: Die Anfrage wurde akzeptiert und eine Vorhersage-ID zurückgegeben, aber die Generierung schlug während der asynchronen Verarbeitung fehl.
API-Ebene-Fehler
API-Ebene-Fehler treten synchron auf. Wenn Sie eine POST-Anfrage an /v1/run oder eine GET-Anfrage an /v1/status/{id} stellen, validiert der Server die Anfrage, bevor er intensive Hintergrundarbeiten beginnt.
Schlägt die Validierung fehl, gibt die API einen HTTP-Fehlerstatus (z.B. 400, 401) zurück, und die JSON-Antwort enthält eine error-Nachricht und einen spezifischen String-code.
{
"error": "Invalid request payload. Expected { model_name, inputs }",
"code": "BadRequest"
}Standard-Fehlercodes
| Code | Fehler | Ursache | Behebung |
|---|---|---|---|
| 400 | BadRequest | Ungültiges Anfrageformat oder nicht unterstützter Modellname | Überprüfen Sie die JSON-Struktur, stellen Sie sicher, dass model_name korrekt ist, und verifizieren Sie, dass alle erforderlichen inputs bereitgestellt wurden. |
| 401 | UnauthorizedAccess | Ungültiger oder fehlender API-Schlüssel | Verifizieren Sie, dass der Header Authorization: Bearer YOUR_API_KEY korrekt ist und der Schlüssel aktiv ist. |
| 402 | OutOfCredits | Keine Entwickler-API-Guthaben mehr vorhanden | Füllen Sie Ihre Guthaben im Fit It On Dashboard auf, bevor Sie es erneut versuchen. |
| 403 | Forbidden | Unautorisierter Zugriff auf Vorhersage | Sie versuchen, den Status einer Vorhersage zu überprüfen, die mit einem anderen Entwicklerschlüssel erstellt wurde. |
| 404 | NotFound | Vorhersage nicht gefunden | Bestätigen Sie, dass die Vorhersage-ID korrekt ist, wenn Sie den Status-Endpunkt abfragen. |
| 413 | PayloadTooLarge | Payload überschreitet Limits | Stellen Sie sicher, dass Eingabebilder unter 25 MB liegen und angemessene Auflösungen verwenden. |
| 500 | InternalServerError | Serverseitiger Fehler | Wiederholen Sie mit exponentiellem Backoff. Kontaktieren Sie den Support, wenn das Problem weiterhin besteht. |
[!TIP] Wiederholungen und Idempotenz Wenn Sie auf einen API-Ebene-Fehler stoßen, können Sie dieselbe Payload sicher erneut versuchen, sobald das Problem behoben ist. Da die Anfrage sofort abgelehnt wurde, wurden keine Guthaben abgezogen und eine doppelte Verarbeitung ist kein Risiko.
Laufzeitfehler
Laufzeitfehler treten auf, nachdem die API Ihre Anfrage erfolgreich akzeptiert und eine Vorhersage-ID zurückgegeben hat.
Da Generierungsmodelle stark asynchron sind, werden Sie diese Fehler beim Abfragen des /v1/status/{id}-Endpunkts entdecken. Schlägt ein Hintergrundjob fehl, gibt der Endpunkt einen HTTP 200 OK zurück (da die Abfrageanfrage selbst erfolgreich war), aber das status-Feld innerhalb der Payload wird "failed" sein.
Die Antwort enthält die Vorhersage-ID und ein error-Objekt, das detailliert beschreibt, was schiefgelaufen ist, einschließlich eines kategorisierten name und einer beschreibenden message.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "failed",
"output": null,
"error": {
"name": "ImageLoadError",
"message": "Failed to load input image: URL returned 404"
},
"created_at": "2024-05-15T12:00:00Z",
"updated_at": "2024-05-15T12:00:10Z"
}Häufige Laufzeitfehler
Die meisten Laufzeitprobleme fallen in eine Handvoll gemeinsamer Kategorien über unsere Modelle hinweg:
| Kategorie | Typische Fehlermeldungen | Behebung |
|---|---|---|
| Bildladefehler | Bild konnte nicht abgerufen werden, Ungültige Bild-URL | Stellen Sie sicher, dass die bereitgestellten URLs öffentlich zugänglich sind und keine Authentifizierung erfordern. Bei Base64 stellen Sie sicher, dass es das korrekte MIME-Typ-Präfix enthält. |
| Eingabevalidierung | Bildauflösung zu klein, Fehlender erforderlicher Parameter | Stellen Sie sicher, dass Ihre Eingabedaten die Mindestabmessungen und Anforderungen für das spezifische Modell erfüllen. |
| Inhaltsmoderation | NSFW-Inhalt erkannt, Sicherheitsblock ausgelöst | Ersetzen oder passen Sie das Eingabebild oder den Text-Prompt an, um den Sicherheitsfiltern zu entsprechen. |
| Pipeline-Fehler | Generierung fehlgeschlagen, Serverfehler | Ein unerwarteter Fehler ist im GPU-Cluster aufgetreten. Wiederholen Sie die Anfrage mit exponentiellem Backoff. |
[!NOTE] Guthabenrückerstattungen bei Fehlern Fehlgeschlagene Vorhersagen verbrauchen keine Guthaben. Wenn eine Generierung während der Laufzeit fehlschlägt (z.B. aufgrund eines
Image Load Erroroder einesPipeline Error), werden die zu Beginn der Anfrage abgezogenen Guthaben automatisch auf Ihr Entwicklerguthaben zurückerstattet.
Endpunkt-spezifische Fehler
Bestimmte Modelle haben strenge, workflow-spezifische Validierungsregeln, die während der Generierung ausgeführt werden:
- Pose Control: Schlägt fehl, wenn im Zielbild kein menschlicher Körper erkannt wird.
- Virtual Try-On: Schlägt fehl, wenn es kein gültiges Kleidungsstück im Kleidungsstückbild erkennen kann.
- Model Generation: Schlägt fehl, wenn das bereitgestellte Referenzbild des Gesichts kein klares, unverdecktes Gesicht enthält.
Wenn Sie weiterhin Laufzeitfehler feststellen, nachdem Sie die Eingaben mit der Dokumentation abgeglichen haben, kontaktieren Sie bitte den Support mit Ihrer Vorhersage-ID, damit wir dies untersuchen können.