HiAPI gibt 403 ohne Modellberechtigung zurück: Anleitung zur Fehlersuche und Behebung

Wenn beim Aufruf der HiAPI-Schnittstelle /v1/tasks ein HTTP 403 empfangen wird, sieht der Response-Body in der Regel so aus: {"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}. Das bedeutet, dass dein API-Key selbst gültig ist und die Authentifizierung bereits erfolgreich war, dieser Key jedoch nicht berechtigt ist, das von dir angefragte Modell oder die Schnittstelle aufzurufen – das ist ein anderes Problem als der 401-Fehler „Key ungültig oder fehlend“: Bei 401 wurde die Identität nicht einmal erkannt, bei 403 wurde sie erkannt, aber dieser Key darf die aktuelle Ressource nicht nutzen. Die meisten 403-Fehler lassen sich direkt beheben: Prüfe die Zuordnung von Key und Modell und versuche es mit einem berechtigten Key erneut.

Häufige Ursachen

1. Der API-Key ist nicht zur Nutzung des aktuell angefragten Modells berechtigt – die offizielle Dokumentation definiert 403 genau als „API-Schlüssel hat diese Berechtigung nicht“. Dies ist der häufigste Auslöser und tritt typischerweise auf, wenn mit demselben Key ein Modell außerhalb des Berechtigungsumfangs aufgerufen wird.
2. Falscher Key verwendet – zum Beispiel wurde statt des Haupt-Keys versehentlich ein Key mit geringerem Berechtigungsumfang aus einem anderen Konto oder Projekt verwendet; beim Kopieren und Einfügen können auch leicht überflüssige Leerzeichen oder Abschneidungen entstehen.
3. „Schlüssel ungültig“ (401) und „Schlüssel ohne Berechtigung“ (403) verwechselt – in beiden Fehlermeldungen können Begriffe rund um „Berechtigung“ auftauchen; eine Fehlersuche nach demselben Schema führt in die falsche Richtung. Die genaue Unterscheidung findest du unten.

Behebungsschritte

1. Zunächst bestätigen, dass tatsächlich 403 und nicht 401 zurückgegeben wird – achte auf den HTTP-Statuscode selbst, nicht nur auf den Text der Fehlermeldung, denn der Fehlercode permission_denied kann sowohl bei 401 als auch bei 403 auftreten; entscheidend ist der Statuscode, nicht der Text.
2. In der API-Schlüsselverwaltung die Zugehörigkeit dieses Keys prüfen – stelle sicher, dass der tatsächlich in der Anfrage verwendete Key der erwartete ist und nicht ein Key aus einem Testkonto, einem alten Projekt oder einem fremden Konto.
3. Prüfen, ob das aktuelle Modell im verfügbaren Bereich dieses Keys liegt – anhand der Authentifizierungsdokumentation und der HiAPI-Preise kannst du bestätigen, dass das Modell selbst existiert und in deinem aufrufbaren Bereich liegt; ist die Modell-ID selbst falsch geschrieben oder wurde das Modell abgeschaltet, sollte ein anderer Fehlercode statt permission_denied erscheinen – damit lässt sich die Problemart zusätzlich eingrenzen.
4. Mit einem nachweislich berechtigten Key und exakt denselben übrigen Parametern erneut versuchen, um zu prüfen, ob das Problem mit dem Key-Wechsel verschwindet.
5. Wenn Key und Modell nach der Prüfung in Ordnung sind und der 403 weiterhin stabil reproduzierbar ist, notiere die request_id aus dem Response-Body und kontaktiere den Support; wiederhole dieselbe Anfrage nicht endlos, ohne die Ursache geklärt zu haben.

Minimales Verifizierungsbeispiel

Im Folgenden zeigen eine Anfrage, die einen 403 auslöst, und ein erneuter Versuch nach der Behebung die tatsächlichen Antwortstrukturen in beiden Zuständen (ersetze MODEL_ID durch das Modell, das du tatsächlich aufrufst und bei dem du eine fehlende Berechtigung vermutest):

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "a simple test prompt"
  }'

Antwort ohne Berechtigung:

{
  "error": {
    "code": "permission_denied",
    "message": "当前 API Key 暂不能使用该模型，请检查权限或更换 Key。",
    "request_id": "req_xxxxxxxx",
    "type": "hiapi_error"
  }
}

Erneuter Versuch mit einem berechtigten Key und unveränderten übrigen Parametern:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-xxxxxxxx" },
  "message": "success"
}

Man erkennt, dass die beiden Response-Bodies unterschiedlich aufgebaut sind: Fehler auf Authentifizierungs-/Berechtigungsebene wie 403 werden einheitlich in ein error-Objekt verpackt; Fehler, die entstehen, nachdem der Key die Berechtigungsprüfung bestanden hat und tatsächlich in die konkreten Geschäftsregeln eintritt (zum Beispiel 402 bei unzureichendem Guthaben), werden flach als code / data / message zurückgegeben. Anhand der Struktur lässt sich grob erkennen, ob das Problem auf der Authentifizierungs-/Berechtigungsebene oder in den konkreten Geschäftsregeln liegt.

Verwandte interne Links

• API-Schlüsselverwaltung
• Authentifizierungsdokumentation
• HiAPI-Preise

FAQ

Was genau ist der Unterschied zwischen 403 und 401? 401 bedeutet, dass der Key selbst ungültig ist oder in der Anfrage gar kein Key mitgeschickt wurde – die Identitätsauthentifizierung wurde nicht bestanden. 403 bedeutet, dass die Authentifizierung bestanden wurde (der Key selbst gültig ist), dieser Key jedoch nicht berechtigt ist, das von dir angefragte Modell oder die Ressource zu nutzen. Die Response-Body-Struktur ist bei beiden gleich (beide sind ein in ein error.code-Objekt verpackter Fehler); entscheidend für die Unterscheidung ist der HTTP-Statuscode selbst, nicht der Text in der Fehlermeldung.

Nach dem Wechsel des Keys tritt immer noch 403 auf – liegt ein Kontoproblem vor? Prüfe zunächst, ob der neue Key tatsächlich zu demselben berechtigten Konto oder Projekt gehört und beim Kopieren und Einfügen keine überflüssigen Leerzeichen, Zeilenumbrüche oder Abschneidungen entstanden sind. Wenn das Problem nach der Prüfung weiterhin reproduzierbar ist, kontaktiere den Support unter Angabe der request_id aus dem Response-Body.

Liegt 403 an unzureichendem Guthaben? Nein. Unzureichendes Guthaben entspricht einem anderen Fehlercode (INSUFFICIENT_QUOTA, HTTP 402) und hat nichts mit Berechtigungen zu tun – 403 besagt nur, ob „dieser Key berechtigt ist, dieses Modell aufzurufen“, und ist unabhängig von der Höhe des Kontoguthabens.

Ist es immer 403, wenn in der Fehlermeldung das Wort „Berechtigung“ auftaucht? Nicht unbedingt. Der Fehlercode permission_denied kann sowohl bei 401 als auch bei 403 auftreten; man darf sich nicht allein auf Textschlüsselwörter verlassen, sondern muss direkt den HTTP-Statuscode selbst prüfen.