HiAPI restituisce 403 nessun permesso sul modello: guida alla diagnosi e alla risoluzione

Quando chiami l'endpoint /v1/tasks di HiAPI, se ricevi un HTTP 403 il corpo della risposta ha di solito questa struttura: {"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}. Questo indica che la tua API Key è di per sé valida e l'autenticazione è già passata, ma questa Key non è autorizzata a chiamare il modello o l'endpoint che hai richiesto — si tratta di un problema diverso dal 401 «Key non valida o mancante»: il 401 significa che l'identità non è stata riconosciuta affatto, il 403 che è stata riconosciuta ma questa Key non può usare la risorsa corrente. La maggior parte dei 403 si risolve in modo diretto: verifica la corrispondenza tra Key e modello e riprova con una Key che abbia i permessi.

Cause comuni

1. L'API Key non è autorizzata a usare il modello richiesto — la definizione ufficiale del 403 nella documentazione è «la chiave API non ha questo permesso»; è lo scenario più frequente e di solito si verifica quando si usa la stessa Key per chiamare modelli al di fuori del suo ambito di permessi.
2. Key sbagliata — ad esempio si sarebbe dovuta usare la Key principale ma si è usata per errore una Key con ambito di permessi più ristretto di un altro account o progetto; durante il copia-incolla è anche facile inserire spazi superflui o troncare la stringa.
3. Confondere «chiave non valida» (401) e «chiave senza permessi» (403) — in entrambi i messaggi di errore possono comparire parole legate ai «permessi»; diagnosticare con lo stesso approccio porta nella direzione sbagliata. Per i criteri di distinzione vedi sotto.

Passi di risoluzione

1. Prima conferma che si tratti davvero di un 403 e non di un 401 — guarda il codice di stato HTTP stesso, non solo il testo del messaggio, perché il codice di errore permission_denied può comparire sia sotto 401 sia sotto 403; il discrimine è il codice di stato, non il testo.
2. Vai alla gestione delle chiavi API e verifica l'appartenenza di questa Key — assicurati che la Key effettivamente usata nella richiesta sia proprio quella prevista, e non una Key di un account di test, di un vecchio progetto o di un altro account.
3. Verifica che il modello corrente rientri nell'ambito di utilizzo di questa Key — puoi confrontare la documentazione sull'autenticazione e i prezzi di HiAPI per confermare che il modello esista davvero e rientri nel tuo ambito di chiamata; se l'ID del modello è scritto male o è stato dismesso, l'errore dovrebbe essere un altro codice e non permission_denied: puoi usare questo elemento per distinguere il tipo di problema.
4. Sostituisci la Key con una di cui hai confermato i permessi e riprova con tutti gli altri parametri identici, per verificare se il problema scompare cambiando Key.
5. Se dopo la verifica sia la Key sia il modello sono a posto e il 403 si riproduce ancora stabilmente, annota il request_id presente nel corpo della risposta e contatta il supporto; non riprovare ripetutamente la stessa richiesta senza aver prima confermato la causa.

Esempio minimo di verifica

Qui sotto mostriamo una richiesta che genera un 403 e il nuovo tentativo dopo la risoluzione, per illustrare la struttura reale delle risposte nei due stati (sostituisci MODEL_ID con il modello che stai effettivamente chiamando e che sospetti non abbia i permessi):

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"
  }'

Risposta in caso di mancanza di permessi:

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

Dopo aver sostituito la Key con una che ha i permessi, lasciando invariati gli altri parametri, si riprova:

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

Si può notare che la struttura dei due corpi di risposta è diversa: gli errori a livello di autenticazione/permessi come il 403 usano uniformemente un oggetto avvolto in error; invece gli errori che si verificano dopo che la Key ha superato la verifica dei permessi ed è entrata effettivamente nella valutazione delle regole di business specifiche (ad esempio il 402 per saldo insufficiente) hanno un corpo di risposta con struttura piatta code / data / message. A seconda della struttura che vedi, puoi capire all'incirca se il problema è a livello di autenticazione/permessi o a livello di regole di business specifiche.

Link interni correlati

• Gestione delle chiavi API
• Documentazione sull'autenticazione
• Prezzi di HiAPI

FAQ

Qual è la differenza concreta tra 403 e 401? Il 401 indica che la Key stessa non è valida, oppure che nella richiesta non è stata inclusa affatto la Key — il passo di autenticazione dell'identità non è stato superato. Il 403 indica che l'autenticazione è passata (la Key è valida), ma questa Key non è autorizzata a usare il modello o la risorsa che hai richiesto. La struttura del corpo di risposta è la stessa (un oggetto avvolto in error.code); il discrimine è il codice di stato HTTP stesso, non il testo del messaggio di errore.

Dopo aver cambiato Key ricevo ancora 403: c'è un problema con l'account? Prima conferma che la nuova Key appartenga davvero allo stesso account o progetto con i permessi e che durante il copia-incolla non ci siano spazi superflui, a capo o troncamenti. Se dopo la verifica il problema si riproduce ancora, contatta il supporto indicando il request_id presente nel corpo della risposta.

Il 403 è dovuto a saldo insufficiente? No. Il saldo insufficiente corrisponde a un altro codice di errore (INSUFFICIENT_QUOTA, HTTP 402) ed è una cosa diversa dai permessi — il 403 indica solo «se questa Key ha o meno il diritto di chiamare questo modello» ed è indipendente dall'importo del saldo dell'account.

Se nel messaggio di errore compare la parola «permessi», è sempre un 403? Non necessariamente. Il codice di errore permission_denied può comparire sia sotto 401 sia sotto 403; non si può giudicare solo dalle parole chiave del testo, bisogna guardare direttamente il codice di stato HTTP stesso.