Unif API DocsFehler
Jeder Fehler, den UnifAPI an Agenten und HTTP-Clients zurückgibt, was er bedeutet und wie man sich erholt.
Fehler kommen immer im selben Envelope zurück, unabhängig davon, welche Public-Data-Operation aufgerufen wurde:
{
"error": {
"type": "rate_limited",
"message": "Workspace rate limit exceeded.",
"request_id": "unif_5471f8cfa3814204a280b73df8c93167"
}
}error.typestammt aus einem geschlossenen Vokabular (siehe Tabelle unten) — stabil, maschinenlesbar, sicher für Agenten und Clients zum Umschalten.error.messageist für Menschen und kann sich ohne Vorankündigung ändern.error.request_idist die UnifAPI-Trace-id. Gib sie bei Support-Anfragen an.error.issuesist nur vorhanden, wenntype = validation_error— es ist die rohe Zod-Issue-Liste.
Der HTTP-Status spiegelt den Typ wider — Clients können das jeweils bevorzugte Signal wählen.
Referenz
| Status | type | Wann es passiert | Erholung |
|---|---|---|---|
| 400 | validation_error | Request scheiterte an der Gateway-seitigen Validierung (falsche Query, fehlendes Body-Feld). | Prüfe error.issues. Korrigiere den Request. |
| 400 | invalid_id | Die angegebene id war syntaktisch gültig, wurde aber von der öffentlichen Quelle nicht akzeptiert. | Nutze eine echte id. |
| 401 | unauthorized | OAuth- oder API-key-Anmeldedaten fehlen, sind fehlerhaft, widerrufen oder deaktiviert. | Authentifiziere dich neu oder rotiere den Key. |
| 404 | not_found | Die Ressource (Video, User, Room, ...) existiert nicht, ist gelöscht oder privat. | Bestätige die id; manche Ressourcen sind privat und liefern bewusst 404. |
| 429 | rate_limited | Workspace- oder Quell-Rate-Limit überschritten. | Beachte Retry-After. Siehe Rate Limits. |
| 500 | internal_error | UnifAPI selbst ist fehlgeschlagen (nicht abgefangene Exception). | Sicher wiederholbar. Melde request_id, wenn es bestehen bleibt. |
| 500 | response_shape_error | Quelldaten passen nicht mehr zum veröffentlichten Schema. | Melde request_id — Drift ist ein Bug. |
| 502 | upstream_error | Eine Public-Data-Quelle gab einen Fehler zurück, von dem UnifAPI sich nicht erholen kann. | Prüfe error.message. |
| 503 | upstream_unavailable | Eine Public-Data-Quelle hat ein Timeout oder ist nicht erreichbar. | Wiederhole mit exponentiellem Backoff. |
Die obige Tabelle ist der öffentliche Vertrag für das aktuelle Fehlervokabular.
Anatomie eines Validierungsfehlers
Bei validation_error trägt das issues-Array die rohe Zod-Issue-Liste, damit ein Agent oder Aufrufer Fehler auf Felder zurückführen kann:
{
"error": {
"type": "validation_error",
"message": "Request validation failed.",
"issues": [
{
"code": "too_big",
"maximum": 50,
"type": "number",
"inclusive": true,
"path": ["limit"],
"message": "Number must be less than or equal to 50"
}
]
}
}Logge immer request_id
Jede Fehlerantwort trägt request_id, wenn UnifAPI eine anhängen kann. Logge sie und gib sie bei Support-Anfragen an; sie ist der schnellste Weg, einen fehlgeschlagenen Skill-Lauf oder HTTP-Aufruf zu debuggen.