Dati della chiave API non validi: cause di questo errore e come risolverlo

Quando si chiama hiapi e si vede un messaggio simile a "the api keys data are invalid" (o una variante analoga prodotta dalla tua applicazione), significa che la richiesta non è stata autenticata affatto. A basso livello, l'API di hiapi stessa restituisce per questo un errore specifico: HTTP 401, error.code: "permission_denied", con il messaggio "This API key is invalid. Check that it is correct or use another API key and try again." (Questa chiave API non è valida. Verifica che sia corretta oppure usa un'altra chiave API e riprova.) Qualsiasi applicazione che incapsula hiapi — proxy backend, client compatibili con OpenAI, SDK interni — rietichetta lo stesso 401 con parole proprie: ecco perché il testo esatto che vedi raramente coincide con l'originale di hiapi. Questa guida spiega passo dopo passo perché accade e come verificarlo e risolverlo in pochi minuti.

Che aspetto ha effettivamente l'errore

Una richiesta fallita a POST https://api.hiapi.ai/v1/tasks (o a qualsiasi altro endpoint hiapi) restituisce:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: <id>",
    "request_id": "<id>",
    "type": "hiapi_error"
  }
}

Il codice di stato HTTP è 401. Se il tuo framework o SDK non espone la risposta grezza, potrebbe riconfezionarla in un messaggio generico tipo "API key(s) data are invalid", "unauthorized" o "invalid credentials" — ma la causa radice lato hiapi è sempre lo stesso 401.

Cause comuni (in ordine di probabilità decrescente)

1. Valore della chiave errato. Un copia-incolla troncato, uno spazio di troppo, oppure un valore copiato da vecchi appunti invece che dalla chiave attiva in Dashboard → API Keys, attivano esattamente questo errore — sia che la chiave sia illeggibile, vuota o del tutto inesistente, il messaggio restituito da hiapi è identico.
2. Chiave segnaposto mai sostituita. Il codice copiato da tutorial o template contiene spesso una stringa letterale come sk-your-api-key — produce un 401 esattamente come una stringa casuale.
3. Chiave ruotata o revocata. Creare una nuova chiave nella dashboard non invalida automaticamente quella vecchia, ma la revoca manuale o la rigenerazione sì — se un deployment fa ancora riferimento al vecchio valore (variabile d'ambiente non ridistribuita, .env non ricaricato), ogni richiesta restituirà 401.
4. Chiave inviata nell'header sbagliato. hiapi legge la chiave solo dall'header Authorization. Inviarla come x-api-key, api-key o parametro di query produce la stessa risposta permission_denied, perché in quel caso hiapi non vede affatto la chiave malformata — semplicemente non vede alcuna chiave.
5. Variabile d'ambiente vuota a runtime. Se il processo legge la variabile della chiave prima di caricare il file .env, invierà una stringa vuota come chiave — anche in questo caso 401.
6. Spazi nascosti o caratteri di nuova riga nella chiave. È subdolo: passare un segreto tramite pipe con echo in uno script shell aggiunge un carattere di nuova riga in coda al valore. Se finisce nell'header Authorization, compromette la richiesta in un altro modo — non un pulito 401, ma un 400 con un messaggio illeggibile invalid json body, perché l'header corrotto si riversa nel corpo della richiesta. Se il tuo errore sembra una richiesta malformata invece di un pulito "invalid key", controlla prima che la chiave non contenga spazi o newline indesiderati.

Correzione passo dopo passo

1. Apri Dashboard → API Keys e copia di nuovo la chiave. Non riutilizzare valori dalla cronologia del terminale o da messaggi vecchi — copia direttamente dalla pagina.
2. Verifica che il formato dell'header corrisponda esattamente: Authorization: Bearer YOUR_API_KEY. Se assembli questo valore in uno script shell, usa printf invece di echo — echo aggiunge un carattere di nuova riga in coda che printf non aggiunge.
3. Stampa il valore prima che parta la richiesta (console.log, print o un log di debug) per confermare che non sia vuoto e non contenga virgolette, spazi o newline indesiderati.
4. Testa la chiave isolandola dalla tua applicazione con una semplice chiamata curl (vedi sotto). Se curl funziona e la tua applicazione continua a fallire, il bug sta in come la tua applicazione costruisce la richiesta, non nella chiave.
5. Controlla il codice di stato HTTP esatto che ricevi. 401 è questo errore. 402 significa saldo del conto esaurito, non chiave errata. 403 significa che la chiave è valida ma manca il permesso per quel modello specifico. 429 significa che sei soggetto a rate limit. Nessuno di questi tre va trattato come problema di chiave non valida.

Esempio minimo di verifica

Esegui direttamente il comando seguente (sostituendo con la tua chiave reale) per confermare se la chiave stessa ha problemi:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "input": {"prompt": "a small red apple on a white background"}}'

Una chiave valida restituisce immediatamente un ID attività:

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

Una chiave errata restituisce il 401 mostrato sopra. Se curl restituisce una risposta con taskId ma la tua applicazione lancia ancora l'errore "invalid key", il problema sta nel codice della tua applicazione che costruisce la richiesta, non nella chiave.

Contenuti correlati

• Authentication docs —— formato completo dell'header, guida alla rotazione delle chiavi e riferimento ai codici di stato.
• Dashboard → API Keys —— dove creare, copiare e revocare le chiavi.
• Rate limits —— differenza tra 429 e 401 e condizioni che li attivano.
• Quickstart —— se stai configurando hiapi per la prima volta, qui trovi la procedura completa per la prima richiesta.

Domande frequenti

"invalid API key" e il rate limiting sono la stessa cosa? No. Il 401 permission_denied significa che la chiave stessa non è stata accettata. Il 429 con error_code: "RATE_LIMITED" significa che la chiave è corretta ma le richieste arrivano troppo velocemente — per le soglie consulta la documentazione sui rate limit.

Ho appena creato una nuova chiave, ma resta non valida — perché? Assicurati che la nuova chiave sia stata effettivamente copiata nel punto in cui parte la richiesta. Una nuova chiave nella dashboard non corregge automaticamente un vecchio valore hardcoded, una variabile d'ambiente non impostata o un file di configurazione non ridistribuito.

hiapi richiede la parola letterale "Bearer" nell'header? Il formato documentato e supportato è Authorization: Bearer YOUR_API_KEY — usalo sempre. Non affidarti a comportamenti permissivi che potresti aver osservato nei test; i comportamenti non documentati possono cambiare senza preavviso.

Perché curl funziona e la mia applicazione no? Se curl con la stessa chiave funziona, la chiave è valida e il problema sta in come la tua applicazione assembla la richiesta — di solito manca il prefisso Bearer nel codice, la variabile d'ambiente viene letta prima del caricamento di .env, oppure la chiave viene passata al parametro sbagliato in una libreria wrapper.

Cosa significa error.type: "hiapi_error"? È l'involucro generico degli errori di hiapi, usato sia per questo errore di autenticazione sia per altri errori di richiesta. Controlla error.code (qui permission_denied) per capire l'errore reale, non solo il tipo di involucro.