> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastino.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Use https://docs.fastino.ai/llms.txt to discover and navigate pages. Use https://docs.fastino.ai/llms-full.txt when you need the complete documentation corpus. Use https://docs.fastino.ai/openapi.json as the source of truth for customer-facing routes. For GLiDE decision inference, call POST https://api.fastino.ai/v1/systemone with model fastino/GLiDE. Do not infer undocumented routes. Read API keys from FASTINO_API_KEY and never embed credentials in code, logs, or reports.
# Fastino-API-Fehlercodes und Antwortformate
> Alle 4xx- und 5xx-Statuscodes der Fastino API, das JSON-Antwortformat je Fehlerfamilie und Wege zur Behebung von Billing-, Rate-Limit- und Validierungsfehlern.
Die Fastino API verwendet standardmäßige HTTP-Statuscodes, um das Ergebnis jeder Anfrage zu kommunizieren. Codes im Bereich `2xx` weisen auf Erfolg hin. Codes im Bereich `4xx` weisen auf ein Problem mit Ihrer Anfrage hin, das Sie beheben können. Codes im Bereich `5xx` weisen auf ein serverseitiges Problem hin.
## Format der Fehlerantwort
Die meisten Fehlerantworten geben einen JSON-Body mit einem `detail`-Feld zurück:
```json theme={null}
{
"detail": "..."
}
```
Einige Antwortfamilien verwenden eine andere Struktur:
* **Abrechnungsablehnungen** (`402`, einige `403`) geben `{"code", "message", "resolution_url"}` anstelle von `detail` zurück – siehe [402](#402-zahlung-erforderlich) und [403](#403-verboten) unten.
* **Aufwärm-Antworten** (`425`) enthalten einen `Retry-After`-Header. OpenAI-förmige Bodies enthalten zusätzlich `code: "model_warming"` – siehe [425](#425-zu-früh) unten.
* **Rate-Limit-Antworten** (`429`) fügen neben `detail` die Felder `code` und `scope` sowie die Header `X-RateLimit-Scope` und `X-RateLimit-Code` hinzu – siehe [429](#429-zu-viele-anfragen) unten.
* **Unbehandelte Serverfehler** (`500`) geben `{"error", "message"}` anstelle von `detail` zurück.
* Anfragen an die OpenAI-kompatiblen Endpunkte (`/v1/chat/completions`, `/v1/responses`) erhalten einen OpenAI-förmigen `{"error": {"code", "type", "param", "message"}}`-Umschlag, und Anfragen mit einem `anthropic-version`-Header erhalten stattdessen einen Anthropic-förmigen `{"type": "error", "error": {"type", "message"}}`-Umschlag anstelle der oben genannten generischen Strukturen.
## Statuscodes
### 400 - Ungültige Anfrage
Die Anfrage selbst ist fehlerhaft – ungültiges JSON oder ein Query-/Pfadparameter vom falschen Typ.
**Behebung:** Stellen Sie sicher, dass Ihr Anfrage-Body gültiges JSON ist und dass Query-/Pfadparameter den in der Endpunkt-Referenz dokumentierten Typen entsprechen.
***
### 401 - Nicht autorisiert
Ihre Anfrage enthielt keinen gültigen API-Schlüssel, der Schlüssel wurde widerrufen oder Ihr Konto wurde aufgrund einer Abrechnungs- oder Betrugsprüfung gesperrt.
**Behebung:** Vergewissern Sie sich, dass der Header `X-API-Key` vorhanden ist und Ihren aktuellen Schlüssel enthält. Wenn Sie den Schlüssel kürzlich widerrufen haben, erstellen Sie unter **Settings** → **API Keys** einen neuen. Ist Ihr Konto gesperrt, wenden Sie sich an [support@pioneer.ai](mailto:support@pioneer.ai). Anweisungen zur Einrichtung finden Sie unter [Authentifizierung](/de/authentication).
***
### 402 - Zahlung erforderlich
Eine `402`-Antwort bedeutet, dass Ihrem Konto keine ausgabefähigen Credits mehr zur Verfügung stehen oder eine Abrechnungsaktion erforderlich ist, bevor Inferenz ausgeführt werden kann. Alle API-Aufrufe schlagen fehl, bis Sie Credits hinzufügen oder Ihren Tarif upgraden. Besuchen Sie **Settings** → **Billing** oder siehe [Pläne & Preise](/de/pricing), um dies zu beheben.
Ihr Konto verfügt nicht über ausreichende Credits, um die Anfrage abzuschließen. Das `code`-Feld im Antwort-Body gibt an, welcher Fall zutrifft – am häufigsten `out_of_credits` (Ihre enthaltenen Credits sind aufgebraucht und es gibt kein ausgabefähiges bezahltes Guthaben) oder `direct_model_requires_credits` (der direkte Aufruf eines unterstützten Modells erfordert ein bezahltes Guthaben).
**Behebung:** Melden Sie sich unter [Fastino](https://agent.fastino.ai) an, gehen Sie zu **Settings** → **Billing** und laden Sie Ihr Guthaben auf oder upgraden Sie Ihren Tarif. Unter [Credit-Limits und Ausgabenobergrenze für Overage](/de/api-reference/rate-limits#credit-limits-und-ausgabenobergrenze-für-overage) erfahren Sie, wie Credit-Limits und Overage-Abrechnung funktionieren.
***
### 403 - Verboten
Ihr Team hat die maximale monatliche Overage-Ausgabe seines Tarifs erreicht (`code: "credit_ceiling_reached"`) oder Ihr Konto benötigt eine verifizierte Zahlungsmethode, bevor Inferenz ausgeführt werden kann (`code: "card_required"`).
**Behebung:** Bei einer Ablehnung wegen erreichter Ausgabengrenze upgraden Sie Ihren Tarif unter **Settings** → **Billing**, um die Obergrenze anzuheben. Bei einer Ablehnung wegen Kartenverifizierung fügen Sie eine gültige Zahlungsmethode hinzu. Beide Antworten enthalten eine `resolution_url`, die direkt auf die Seite zur Behebung verweist.
***
### 404 - Nicht gefunden
Die angeforderte Ressource existiert nicht. Dies kann passieren, wenn ein Datensatzname, eine Trainingsjob-ID, eine Evaluations-ID, eine Projekt-ID oder eine Modell-ID falsch geschrieben oder gelöscht wurde.
**Behebung:** Überprüfen Sie die ID oder den Namen im Anfragepfad oder -body sorgfältig. Verwenden Sie den entsprechenden `GET`-Listenendpunkt (zum Beispiel `GET /v1/training-jobs`, `GET /v1/base-models`), um zu bestätigen, dass die Ressource existiert.
***
### 409 - Konflikt
Das Modell existiert im Katalog, kann aber derzeit nicht bedient werden – zum Beispiel ein reines Trainings-Basismodell, das für direkte Inferenz angefordert wurde, oder ein On-Demand-Deployment, dessen Bereitstellung nach Abschluss eines Trainingsjobs noch nicht abgeschlossen ist.
**Behebung:** Prüfen Sie `supports_inference` und `supports_on_demand_inference` für das Modell über `GET /v1/base-models` oder wiederholen Sie den Aufruf, nachdem das Deployment bereitgestellt wurde.
***
### 413 - Nutzdaten zu groß
Der Anfrage-Body – typischerweise ein Datei-Upload für eine Evaluation oder einen Datensatz – überschreitet das Größenlimit des Endpunkts.
**Behebung:** Prüfen Sie in der Endpunkt-Referenz das Upload-Größenlimit und teilen oder komprimieren Sie die Nutzdaten, bevor Sie es erneut versuchen.
***
### 422 - Nicht verarbeitbare Entität
Die Validierung des Anfrage-Bodys ist fehlgeschlagen. Ein erforderliches Feld fehlt, ein Feld hat den falschen Typ oder ein Wert liegt außerhalb des zulässigen Bereichs.
**Behebung:** Prüfen Sie die `message` des Fehlers auf das jeweils fehlgeschlagene Feld. Häufige Ursachen sind:
* Weglassen von `base_model` bei `POST /v1/training-jobs`
* Senden von weniger als 1 oder mehr als 1.000 Strings im `inputs`-Array bei Endpunkten zum Labeln vorhandener Daten
```json theme={null}
{
"detail": "For 'POST /v1/training-jobs', ...",
"errors": [...]
}
```
***
### 425 - Zu früh
Das Modell wärmt sich vorübergehend auf und ist noch nicht bereit, Inferenz zu bedienen. Das ist bei der ersten Anfrage nach einer Zeit ohne Traffic oder gegen ein frisch bereitgestelltes On-Demand-Deployment zu erwarten und bedeutet nicht, dass Ihre Anfrage fehlerhaft ist. Die Aufwärmzeit hängt vom Modell ab, daher kann eine Anfrage mehrmals `425` zurückgeben, bevor sie erfolgreich ist.
Die meisten Endpunkte geben einen OpenAI-förmigen Body mit `code: "model_warming"` zurück:
```json theme={null}
{
"error": {
"message": "...",
"type": "invalid_request_error",
"param": null,
"code": "model_warming"
}
}
```
Anfragen an `/v1/messages` mit einem `anthropic-version`-Header erhalten stattdessen einen Anthropic-förmigen Body ohne `code`-Feld:
```json theme={null}
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "..."
}
}
```
| Header | Wert |
| - | - |
| `Retry-After` | Sekunden bis zum nächsten Versuch. Das ist eine Wiederholungsverzögerung, keine Zusage, dass das Modell dann bereit ist. |
| `x-should-retry` | `true` bei OpenAI-förmigen Antworten, daher wiederholen die OpenAI-SDKs automatisch. `false` bei Anthropic-förmigen Antworten, daher wiederholen die Anthropic-SDKs nicht; behandeln Sie diese selbst. |
**Behebung:** Warten Sie `Retry-After` Sekunden (30, falls der Header fehlt) und senden Sie dieselbe Anfrage erneut, mit einer begrenzten Anzahl von Wiederholungen. Jedes Beispiel wiederholt höchstens 5 Mal, setzt ein Client-Timeout von 300 Sekunden und bricht bei jeder anderen Nicht-2xx-Antwort ab. Dieselbe Schleife funktioniert für `/v1/systemone`; ändern Sie URL und Request-Body.
```bash cURL theme={null}
for attempt in 0 1 2 3 4 5; do
http_code=$(curl -sS --max-time 300 -o response.json -D headers.txt -w "%{http_code}" \
https://api.fastino.ai/v1/chat/completions \
-H "Authorization: Bearer $FASTINO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fastino/gliner2.5-multi-v1",
"messages": [{ "role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino." }],
"schema": { "entities": ["organization", "product"] }
}')
[ "$http_code" = "425" ] && [ "$attempt" -lt 5 ] || break
delay=$(awk 'tolower($1) == "retry-after:" && $2 + 0 > 0 { print $2 + 0 }' headers.txt)
sleep "${delay:-30}"
done
if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
cat response.json
else
echo "Request failed with HTTP $http_code: $(cat response.json)" >&2
fi
```
```python Python theme={null}
import os
import time
import requests
MAX_RETRIES = 5
for attempt in range(MAX_RETRIES + 1):
response = requests.post(
"https://api.fastino.ai/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['FASTINO_API_KEY']}"},
json={
"model": "fastino/gliner2.5-multi-v1",
"messages": [
{"role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino."}
],
"schema": {"entities": ["organization", "product"]},
},
timeout=300,
)
if response.status_code != 425 or attempt == MAX_RETRIES:
break
retry_after = response.headers.get("Retry-After", "")
time.sleep(int(retry_after) if retry_after.isdigit() else 30)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"Request failed: {response.status_code} {response.text}")
print(response.json()["choices"][0]["message"]["content"])
```
```javascript JavaScript theme={null}
const MAX_RETRIES = 5;
let response;
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
response = await fetch("https://api.fastino.ai/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FASTINO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "fastino/gliner2.5-multi-v1",
messages: [{ role: "user", content: "Apple announced the MacBook Pro at WWDC in Cupertino." }],
schema: { entities: ["organization", "product"] },
}),
signal: AbortSignal.timeout(300_000),
});
if (response.status !== 425 || attempt === MAX_RETRIES) break;
const retryAfter = Number(response.headers.get("Retry-After"));
await new Promise((resolve) => setTimeout(resolve, (retryAfter || 30) * 1000));
}
if (!response.ok) {
throw new Error(`Request failed: ${response.status} ${await response.text()}`);
}
const completion = await response.json();
console.log(completion.choices[0].message.content);
```
Mit einem SDK finden Sie unter [Wiederholungen und Modell-Warm-up](/de/troubleshooting/retries), welche Antworten Sie wiederholen sollten und wie Sie Backoff anwenden.
***
### 429 - Zu viele Anfragen
Sie haben ein Anfrage-Rate-Limit für diesen Endpunkt überschritten. Die Antwort enthält einen `Retry-After`-Header sowie die Header `X-RateLimit-Scope` und `X-RateLimit-Code`, die angeben, welches Limit Sie erreicht haben – der JSON-Body führt neben `detail` die passenden Felder `code` und `scope`.
**Behebung:** Beachten Sie den `Retry-After`-Wert und warten Sie, bevor Sie es erneut versuchen. Siehe [Rate Limits](/de/api-reference/rate-limits) für Limits pro Endpunkt und ein Retry-Code-Muster. Beachten Sie, dass Credit- und Overage-Ablehnungen `402`/`403` zurückgeben, nicht `429` – siehe [Credit-Limits und Ausgabenobergrenze für Overage](/de/api-reference/rate-limits#credit-limits-und-ausgabenobergrenze-für-overage).
***
### 451 - Aus rechtlichen Gründen nicht verfügbar
Das angeforderte Modell ist für Ihr Konto aufgrund von Exportkontrollen oder Sanktionsbeschränkungen in Ihrer Region nicht verfügbar.
**Behebung:** In den [FAQ](/de/faq) finden Sie die aktuelle Liste eingeschränkter Regionen und anbieterspezifischer Richtlinien. Wenn Sie glauben, dass Ihr Zugriff fälschlicherweise eingeschränkt wurde, wenden Sie sich an den Support.
***
### 500 - Interner Serverfehler
Auf den Servern von Fastino ist ein unerwarteter Fehler aufgetreten. Dieser wird nicht durch Ihre Anfrage verursacht. Der Body verwendet die Felder `error` und `message` anstelle von `detail`:
```json theme={null}
{
"error": "Internal server error",
"message": "..."
}
```
**Behebung:** Warten Sie einen Moment und versuchen Sie es erneut. Wenn der Fehler weiterhin auftritt, prüfen Sie unter [status.pioneer.ai](https://status.pioneer.ai) den aktuellen Servicestatus oder wenden Sie sich an den Support.
***
### 503 - Dienst nicht verfügbar
Eine für die Anfrage benötigte Abhängigkeit – die Abrechnungsprüfung oder ein Status-/Metrik-Endpunkt eines Anbieters – ist vorübergehend nicht verfügbar.
**Behebung:** Warten Sie einen Moment und versuchen Sie es erneut. Wenn der Fehler weiterhin auftritt, prüfen Sie unter [status.pioneer.ai](https://status.pioneer.ai) den aktuellen Servicestatus oder wenden Sie sich an den Support.
***
### 529 - Überlastet (nur Anthropic-kompatibler Endpunkt)
`POST /v1/messages` spiegelt Anthropics eigene `overloaded_error`-Antwort wider, wenn die vorgelagerte Claude-Kapazität vorübergehend ausgelastet ist.
**Behebung:** Wiederholen Sie mit Backoff, genauso wie Sie es bei einem `429` oder `503` tun würden.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.