Jos jokin ei toimi, nopein tapa selvittää onko vika sinulla vai meillä on tehdä sama pyyntö toisella työkalulla.

Noin 9 kymmenestä "API rikki" -ilmoituksesta osoittautuu väärin määritetyksi base URL:ksi, vanhentuneeksi API-avaimeksi, väärän nimiseksi malliksi tai pyynnön rakenteeksi opetusohjelmasta, joka on kolme SDK-versiota vanhentunut.

Nopea omatoiminen testi

Kopioi tämä curl-komento terminaaliin. Korvaa YOUR_KEY dashboardin API-avaimellasi ja suorita se. Jos saat normaalin vastauksen takaisin, API-avaimesi, verkkosi ja taustajärjestelmämme ovat kaikki kunnossa — mikä tahansa vika on asiakaskoodissasi tai ympäristössäsi.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

ℹ️

Nopea omatoiminen testi: Eikö terminaali ole käsillä? Liitä sama malli ja prompt Playground-näkymään dashboardista — sama vaikutus, ei asennusta.

Vaiheittainen tarkistuslista

Onko API-avaimesi kelvollinen?

Avaa Dashboard → API Keys ja varmista, että avain vastaa koodissasi käyttämääsi. Yleinen ansa on välilyönti "sk-air-"-etuliitteen edessä kopioinnista.

Oire: 401 Unauthorized.

Onko base URL oikein?

Base URL:n on oltava https://api.airforce/v1 — ei http, ja /v1-pääte on pakollinen. Oppaat, jotka ovat peräisin ajalta ennen OpenAI:n v1-polkua, jättävät sen joskus pois.

Oire: 404 Not Found tai curl jää roikkumaan.

Onko mallin nimi kirjoitettu oikein?

Malli-ID:t ovat kirjainkokoriippuvaisia. Käy Models-sivulla tai kutsu GET /v1/models vahvistaaksesi tarkan ID:n. Kirjoitusvirhe tai vanhentunut malli palauttaa selkeän virheen — ei "toimii mutta väärin".

Oire: 400 unknown_model tai 404 model_not_found.

Onko pyynnön runko oikeassa muodossa?

Chat-täydennykset käyttävät messages-taulukkoa. Kuvat käyttävät prompt + n. Audio TTS käyttää input + voice. Chat-muotoisen rungon lähettäminen osoitteeseen /v1/images/generations palauttaa 400 — helppo jättää huomaamatta kopioitaessa katkelmia dokumentaatioiden välillä.

Oire: 400, ja rikkonainen kenttä nimetään vastauksen rungossa.

Oletko osunnut nopeusrajoitukseen tai kiintiön kattoon?

429 = liian monta pyyntöä tässä minuutissa. 402 = suunnitelmasi tai saldosi on loppunut. Molemmat näkyvät Dashboardissa. Ilmaistason pyynnöillä on erilliset rajat maksullisen suunnitelman pyynöistä, joten maksullinen malli saattaa vastata normaalisti, kun ilmainen nopeusrajoittaa.

Oire: 429 Too Many Requests tai 402 Payment Required.

Toimiiko malli juuri nyt?

Tarkista Models-sivu — palveluntarjoajien katkokset näkyvät "degraded"- tai "major outage" -merkintöinä. Jos yksi malli on alhaalla muiden toimiessa, kyse on palveluntarjoajan puolen ongelmasta, johon me reititämme, ei asiakasvirheestä.

Oire: tietty malli palauttaa 5xx-virheen muiden toimiessa.

Mitä HTTP-statuskoodit tarkoittavat

Jokainen virhesvastaus sisältää vakiomuotoisen HTTP-statuskoodin. Kunkin koodin merkityksen tietäminen säästää tukipyynnön.


400	Sinun puolesi	Bad Request — väärin muotoiltu JSON, puuttuva pakollinen kenttä, tuntematon parametri. Korjaa pyynnön runko.
401	Sinun puolesi	Unauthorized — puuttuva tai virheellinen API-avain. Tarkista, että Authorization-otsikko sisältää "Bearer "-etuliitteen.
402	Sinun puolesi	Payment Required — suunnitelma loppu tai Pay-as-you-go-saldo tyhjä. Tilaa tai lataa saldoa.
403	Sinun puolesi	Forbidden — suunnitelmasi tai avainkohtainen oikeutesi ei salli tätä mallia tai endpointia.
404	Sinun puolesi	Not Found — tuntematon endpoint tai malli-ID. Tarkista URL-polku ja mallin oikeinkirjoitus.
413	Sinun puolesi	Payload Too Large — syöte ylittää mallin kontekstiikkunan. Lyhennä promptia.
429	Sinun puolesi	Too Many Requests — nopeusrajoitettu (RPM, RPD tai päivittäinen tokenikatto). Hidasta tai päivitä.
500	Meidän puolemme	Internal Server Error — bugi puolellamme. Raportoi se, jos se jatkuu yli minuutin.
502	Meidän puolemme	Bad Gateway — taustajärjestelmä käynnistyy uudelleen (teemme muutamia käyttöönottoja päivässä). Odota 5–10 sekuntia ja yritä uudelleen.
503	Meidän puolemme	Service Unavailable — jokainen kyseisen mallin yläpuolinen palveluntarjoaja epäonnistui samanaikaisesti. Raportoi, jos se kestää yli muutaman minuutin.

💡

Nyrkkisääntö: 4xx-koodit tarkoittavat, että asiakkaasi teki jotain, jonka palvelin hylkäsi. 5xx-koodit tarkoittavat, että emme onnistuneet käsittelemään kelvollista pyyntöä. Vastauksen JSON-virheen runko nimeää yleensä kentän, joka laukaisi tarkistuksen.

Milloin kyseessä on todellinen bugi

Jos curl-omatoiminen testi yllä toimii mutta täsmälleen sama pyyntö koodistasi ei toimi, ongelma on asiakkaassasi (tai siinä käyttämässäsi kirjastossa). Jos omatoiminen testi itsessään epäonnistuu 5xx-virheellä tai palauttaa 4xx-virheen viestillä, joka ei vastaa pyyntöäsi, se kannattaa raportoida.

Tehokkaan raportoinnin ohjeet

Avaa tukipyyntö dashboardista tai kirjoita #support-kanavalle Discordissa. Sisällytä mukaan:

Täydellinen HTTP-statuskoodi ja vastauksen sisältö (myös cf-ray-vastausotsikko, jos se on läsnä).
Likimääräinen aikaleima UTC-ajassa.
Mallin nimi ja kutsumasi endpoint.
Minimaalinen cURL, joka toistaa ongelman (peitä oikea API-avaimesi!).
Toimiiko yllä oleva omatoiminen testi sinulle samalla avaimella.

ℹ️

Tehokkaan raportoinnin ohjeet: Tukipyynnöt, jotka saapuvat näillä tiedoilla, saavat oikean vastauksen ensimmäisellä yrittämällä. Ilman niitä lähetetyt tukipyynnöt vaativat lähes aina edestakaisin käytyä viestinvaihtoa ennen kuin voimme auttaa.

Kysy kanavalla #support Discordissa

Ennen kuin raportoit bugista