Gabimet e API-së

Kjo faqe ofron një referencë për të gjitha kodet e gabimeve të Interactions API, përshkruan formatin e përgjigjes së gabimit dhe shpjegon se si API-ja i jep gabimet për lloje të ndryshme kërkesash.

Kodet standarde të gabimeve të API-së

Këto kode të përgjithshme gabimi në nivel kërkese korrespondojnë me kodet standarde të statusit HTTP. Përdor fushën code në logjikën e aplikacionit tënd për të menaxhuar gabimet në mënyrë programatike.

Kodi Statusi i HTTP-së Përshkrimi Veprimi i rekomanduar
invalid_request 400 - Kërkesë e gabuar Ngarkesa e kërkesës është me formë të gabuar ose përfshin parametra të pavlefshëm. Kontrollo sintaksën dhe parametrat e kërkesës sate në lidhje me referencën e API-së.
failed_precondition 400 - Kërkesë e gabuar Kërkesa nuk mund të përpunohet sepse nuk është plotësuar një parakusht (për shembull, faturimi i çaktivizuar). Verifiko statusin e faturimit të projektit ose kushtet paraprake të llogarisë.
out_of_range 416 Requested Range Not Satisfiable Parametri i kërkesës është jashtë diapazonit të vlefshëm. Kontrollo vlerat dhe kufijtë e parametrave.
parameter_unknown 400 - Kërkesë e gabuar Kërkesa përmban një parametër të panjohur. Hiq parametrin e panjohur dhe provo përsëri.
authentication 401 E paautorizuar Çelësi i API-së mungon, është i pavlefshëm ose ka skaduar. Verifiko çelësin tënd API.
payment_required 402 Kërkohet pagesë Balanca jote e kreditit me parapagim është shteruar. Shto kredite në llogarinë tënde të faturimit ose aktivizo rimbushjen automatike. Mos provo përsëri: kërkesa nuk do të ketë sukses derisa të shtohen kreditet.
permission_denied 403 E ndaluar Çelësi yt i API-së nuk ka leje për këtë burim ose qasja e API-së së projektit tënd është e kufizuar. Kontrollo lejet e çelësit API, kualifikimin për nivelin e projektit dhe statusin e faturimit. Shiko Zgjidhja e problemeve për projektin e kufizuar ose të padisponueshëm.
not_found 404 Nuk u gjet Burimi i kërkuar nuk u gjet. Verifiko shtegun dhe parametrat e burimit.
model_not_found 404 Nuk u gjet Modeli i specifikuar nuk u gjet. Verifiko emrin e modelit ose kthehu te një model tjetër.
already_exists 409 Konflikt Entiteti që u përpoqe të krijoje ekziston tashmë. Kontrollo nëse burimi ekziston tashmë para se ta rikrijosh.
aborted 409 Konflikt Operacioni u ndërpre për shkak të një dështimi të kontrollit të konfliktit ose të përputhshmërisë. Riprovo kërkesën në një nivel më të lartë aplikacioni.
rate_limit_exceeded 429 Too Many Requests Ke tejkaluar kufirin e kërkesave ose të tokenëve për minutë ose për sekondë. Prit dhe provo përsëri me tërheqje eksponenciale.
quota_exceeded 429 Shumë kërkesa Ke tejkaluar kuotën tënde ditore. Prit derisa të rivendoset kuota ose kërko një rritje të kuotës.
too_many_requests 429 Shumë kërkesa Ke bërë shumë kërkesa brenda një periudhe të shkurtër kohore. Prit dhe provo përsëri me tërheqje eksponenciale.
cancelled 499 Kërkesa e mbyllur nga klienti Klienti e anuloi kërkesën para se të përfundonte. Nuk nevojitet asnjë veprim. Kjo zakonisht do të thotë që klienti është shkëputur.
api_error 500 Gabim i brendshëm i serverit Ndodhi një gabim i papritur në server. Riprovo kërkesën. Nëse vazhdon, kontakto me ekipin e mbështetjes.
unimplemented 501 Nuk është zbatuar Veprimi ose veçoria nuk është zbatuar ose mbështetur. Kontrollo aftësitë e API-së ose kalo te një veçori e mbështetur.
service_unavailable 503 Shërbimi nuk ofrohet Shërbimi është i mbingarkuar përkohësisht ose nuk funksionon. Prit dhe provo përsëri me tërheqje eksponenciale.
deadline_exceeded 504 Skadimi i portëkalimit Kërkesa nuk përfundoi brenda afatit. Hiq ose rrit cilësimin e afatit të klientit për të përdorur cilësimin e parazgjedhur të serverit.

Kodet e bllokimit të gjenerimit

Këto kode gabimi tregojnë se kufizimet e politikës, sigurisë ose përmbajtjes bllokuan rezultatin e modelit. Kur merr një nga këto kode, modifiko hyrjen tënde dhe provo përsëri.

Kodi Përshkrimi
safety Shkeljet e sigurisë (përmbajtjet e dëmshme) e bllokuan kërkesën.
recitation Kufizimet për të drejtat e autorit ose recitimin e bllokuan kërkesën.
language Një gjuhë e pambështetur e bllokoi kërkesën.
prohibited_content Udhëzimet për përmbajtjet e ndaluara e bllokuan kërkesën.
spii Kufizimet për informacionet delikate të identifikueshme personalisht e bllokuan kërkesën.
blocklist Kushtet e ndaluara në një listë bllokimesh e bllokuan kërkesën.
image_safety Shkeljet e sigurisë bllokuan gjenerimin e imazhit.
image_prohibited_content Udhëzimet për përmbajtjet e ndaluara bllokuan gjenerimin e imazhit.
image_recitation Kufizimet për të drejtat e autorit ose recitimin e bllokuan gjenerimin e imazhit.
image_other Arsye të papërcaktuara bllokuan gjenerimin e imazhit.
content_blocked Një arsye e papërcaktuar e politikës e bllokoi kërkesën.

Kodet e gabimeve të gjenerimit

Këto kode gabimi tregojnë një problem strukturor me nxjerrjen e gjeneruar të modelit (si p.sh. një thirrje funksioni me formë të gabuar ose një thirrje vegle të padeklaruar).

Kodi Përshkrimi
malformed_function_call Modeli prodhoi një thirrje funksioni që nuk mund të analizohej.
malformed_tool_call Modeli prodhoi një thirrje vegle që nuk mund të analizohej.
unexpected_tool_call Modeli ka thirrur një vegël që nuk është deklaruar në kërkesë.
no_image Modeli nuk mund të gjeneronte një imazh.
too_many_tool_calls Modeli ka gjeneruar më shumë thirrje të veglave se sa lejohet.
missing_thought_signature Përgjigjes i mungon një nënshkrim i kërkuar i mendimit.

Formati i përgjigjes me gabim

Të gjitha gabimet nga Interactions API kthejnë një objekt error që përmban një code dhe message. Për shembull, kalimi i një lloji vegle që nuk mbështetet kthen:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Fusha Lloji Përshkrimi
code varg Një kod gabimi i lexueshëm nga makineria në snake_case.
message varg Një përshkrim i lexueshëm nga njeriu për atë që shkoi keq.

Si dërgohen gabimet

API-ja i jep gabimet në mënyrë të ndryshme në varësi të faktit nëse bën një kërkesë standarde HTTP apo një kërkesë transmetimi (SSE).

Kërkesat standarde HTTP

Për kërkesat standarde (jo transmetuese), API-ja cakton kodin e statusit të përgjigjes së HTTP-së (si p.sh. 400 Bad Request, 401 Unauthorized ose 429 Too Many Requests) dhe kthen një objekt error në trupin e përgjigjes së JSON-it:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Kërkesat për transmetim (SSE)

Për kërkesat për transmetim (stream: true), API-ja dërgon ngjarje gabimi nëpërmjet transmetimit të Server-Sent Events (SSE) me event_type të caktuar në "error". Fusha error përmban të njëjtën strukturë code dhe message:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Për skemën e plotë të ngjarjeve SSE, shiko Referencën e Interactions API.

Çfarë ka më pas