Vsaka napaka, pojasnjena na stalnem naslovu.
Ta stran je operativna referenca, ne prodajni nagovor. Vsak razred napak API Connect ima tukaj trajno sidro; odgovori API z napako bodo kazali na te naslove. Dobite verjeten vzrok in popravek — v tem vrstnem redu. Nazaj na dokumentacijo za razvijalce.
Ključ manjka, je napačno oblikovan ali neznan
API avtenticira izključno prek glave Authorization: Bearer vgk_… — nikoli prek sejnega piškotka. Preklican ključ postane neznan v trenutku preklica.
Popravek. Preverite, da glava dejansko odide (posredniki jo včasih odstranijo), da se ključ začne z vgk_ in da ni bil preklican iz konzole pisarne. Ker se skrivnost prikaže le ob ustvarjanju, se izgubljen ključ zamenja, ne obnovi.
Potekli ključ
Vsak ključ poteče eno leto po ustvarjanju — datum expire_le je v konzoli pisarne viden od prvega dne. 401 ob poteku je izrecen: pove, da je ključ obstajal in ni več veljaven.
Popravek. Ustvarite nov ključ, nanj preusmerite svoje klice, starega prekličite. To zamenjavo načrtujte v svojih operacijah, namesto da jo odkrijete: datum je znan leto vnaprej.
Nezadosten obseg
Ključi nosijo lecture (branje, privzeto) in/ali ecriture (pisanje). Kvalificiranje dogodka zahteva ecriture; ključ samo za branje prejme 403 ne glede na vir.
Popravek. Ustvarite ključ z zahtevanim obsegom — in samo z njim. Najmanjši privilegij je nameren: integracija, ki samo bere, nima razloga, da bi imela ključ za pisanje.
Ni najdeno — ali pripada drugi pisarni
404 pomeni, da vir ne obstaja ali pripada drugi pisarni. API teh dveh primerov nikoli ne razlikuje: razlikovanje bi razkrilo, kaj obstaja drugje. Ločevanje se uveljavlja na ravni podatkovne baze, ne le v aplikacijski kodi.
Popravek. Preverite seq glede na dnevnik pisarne, ki ji ključ pripada (GET /api/v1/evenements). Če integrirate več pisarn, ima vsaka pisarna svoje ključe: seq ne potuje med pisarnami.
Presežena omejitev zahtev
60 zahtev na minuto na ključ, privzeto (nastavljivo po ključu). Odgovor nosi Retry-After in glave X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Popravek. Upoštevajte Retry-After — brez takojšnjega ponovnega poskusa. Zadeti omejitev med poizvedovanjem je skoraj vedno znak polnega ponovnega branja: kazalec depuisSeq nikoli znova ne prebere že prebranega.
Podpis se na vaši strani ne preveri uspešno
Vaš prejemnik mora znova izračunati v1 = HMAC-SHA256(secret, t + "." + body) iz surovega prejetega telesa in zavrniti vsak t, starejši od 5 min. Klasične napake: telo, ponovno serializirano pred preverjanjem (preoblikovan JSON nima več istih bajtov), ura, ki uide izven tolerance, in prezrta rotacija — 24 ur glava nosi po en v1 za vsako še veljavno skrivnost, sprejeti pa morate, če se ujema katera koli.
Popravek. Preverjajte na surovih bajtih, sinhronizirajte uro (NTP), preizkusite svoje preverjanje med rotacijo. Odlomka Node in Python v dokumentaciji počneta natanko to — raje ju prekopirajte, kot da ju pišete na novo.
Dogodek prispe dvakrat
Dostava je at-least-once, v paketih po največ 100, po vrstnem redu dnevnika; kazalec napreduje šele ob vašem 2xx, paket za paketom. Napaka po prejemu, a pred napredovanjem kazalca, povzroči ponovno dostavo — to je pogodba, ne okvara.
Popravek. seq je vaš idempotentni ključ: vsako zaporedje obdelajte natanko enkrat in z 2xx odgovorite šele po trajnem zapisu. Prezgodnji 2xx, ki mu sledi sesutje, je edini način, da dogodek izgubite.
Dnevnik je videti nepopoln ali se ponavlja
depuisSeq je strogo izključujoč: vrnjeni so le dogodki z višjim seq, urejeni naraščajoče, največ 500 na stran. Odgovor vrne prochainSeq, ki ga podate nespremenjenega. Stran, krajša od limite, pomeni konec dnevnika.
Popravek. prochainSeq trajno shranjujte med zagoni in ga nikoli ne izračunavajte sami. Podvojitve pomenijo, da ste znova začeli s prestarim kazalcem; vrzeli pomenijo, da ste preskočili neuspelo stran, ne da bi jo ponovili.
Parameter izven sheme
Neznan status, razrešitev izven seznama (planifie, traite, ecarte), neceloštevilski limite: odgovor imenuje sporno polje in nič drugega — sporočila o napakah nikoli ne nosijo vsebine zadev.
Popravek. Specifikacija OpenAPI je vir: naštevanja in meje, ki jih deklarira, so tiste, ki jih strežnik uveljavlja, saj jo streže sam.
Nezadosten obseg (API virov)
Končne točke virov (/clients, /dossiers, listine, pregledovanje, opozorila) zahtevajo drobnozrnat obseg: clients:*, dossiers:*, pieces:*, criblage:* ali namenski obseg alertes:qualifier. Podedovani ključ lecture podeli vse obsege *:lecture, ecriture pa vse *:ecriture — a alertes:qualifier se nikoli ne deduje: kvalificiranje opozorila je dejanje odgovorne osebe, ki se prenese tako, da ta obseg označite ob ustvarjanju ključa.
Popravek. Ustvarite ključ z natanko tistimi obsegi, ki jih vaša integracija potrebuje — in samo z njimi. Polje detail v odgovoru imenuje manjkajoči obseg.
Vir ni najden — ali pripada drugi pisarni
Enako pravilo kot #cloisonnement, uporabljeno na virih: stranka, zadeva, listina ali opozorilo, ki ne obstaja ali pripada drugi pisarni, dobi isti 404. API teh dveh primerov nikoli ne loči.
Popravek. Preverite identifikator glede na sezname pisarne, ki ji ključ pripada. Identifikator nikoli ne potuje iz ene pisarne v drugo.
Manjka glava Idempotency-Key
Vsak POST za ustvarjanje ali proženje (stranka, zadeva, listina, pregledovanje, dejanski lastniki) zahteva glavo Idempotency-Key: stabilen niz z največ 200 znaki, po eden na operacijo. Ponovitev istega ključa z istim telesom vrne isti odgovor, brez učinka — vaša zaščita pred podvojitvami ob omrežnem incidentu.
Popravek. Ključ ustvarite pred prvim poskusom (en UUID na poslovno operacijo) in ga nespremenjenega uporabite pri vsakem ponovnem poskusu te iste operacije.
Idempotentni ključ ponovno uporabljen z drugačnim telesom
Ta Idempotency-Key je bil v zadnjih 24 urah že uporabljen za drugačno telo. Ključ ponovi odgovor, nikoli ga ne prepiše: njegova ponovna uporaba za novo operacijo je skoraj vedno znak ključa, izpeljanega iz števca ali okrnjenega datuma.
Popravek. Nov ključ za vsako novo operacijo. Ključa nikoli ne izpeljujte iz podatkov, ki se med operacijami ponavljajo.
Zapečatena zadeva: register je zamrznjen
Pečatenje zamrzne verigo celovitosti zadeve — v tem je njena dokazna vrednost. Zapečatene zadeve ni več mogoče urejati, ne sprejema več listin in se po tem kanalu ne pregleduje več znova. Mogoča ostane le kvalifikacija opozoril: zapiše se zunaj verige, zapečatena glava se nikoli ne premakne.
Popravek. Ničesar ni treba »popraviti«: to je namerna nespremenljivost. Če se morajo podatki spremeniti, je to nova operacija skrbnega pregleda v aplikaciji, ne mutacija zapečatene zadeve.
Format listine ni sprejet
Dokazila sprejemajo PDF, JPG, JPEG, PNG in WEBP — iste formate kot aplikacija. Preverjanje poteka na končnici obveznega polja filename: listina brez veljavnega imena datoteke je zavrnjena, ne glede na vsebino.
Popravek. Pretvorite pred pošiljanjem (sken TIFF ali HEIC se pretvori v PDF ali JPEG) in vsebino pošljite kot standardni base64 v polju contenu, s type med stabilnimi kodami a_doc_*.
Listina nad 6 MB
Omejitev velja za dekodirano datoteko (6 MB), enako kot v aplikaciji in na portalu za zbiranje. Ker base64 doda tretjino kodirne režije, telo zahteve sprejme do 9 MB.
Popravek. Listino raje stisnite (barvni PDF, skeniran pri 300 dpi, v sivinah skoraj vedno pade pod omejitev), kot da jo razdelite.
Vir pregledovanja ni na voljo
Nobenega subjekta zadeve ni bilo mogoče preveriti po seznamih: vir (indeks uradnih seznamov ali ponudnik) ni odgovoril. API zavrača sklepanje — »čisto« poročilo na mrtvem viru bi bil najhujši možni lažni negativni izid. Napaka se zabeleži na zadevi (erreurSource). Delni izpad ne povzroči tega 502: odgovor 200 obdrži zadetke subjektov, ki so odgovorili, in v erreurSourceEntites imenuje tiste, ki so odpovedali.
Popravek. Pozneje ponovite isti klic, z isto Idempotency-Key: idempotentnost si zapomni samo odgovore o uspehu — ponovitev po napaki izvede resnično pregledovanje.
Ta stran se bo razvijala z API-jem; obstoječa sidra pa nikoli ne spremenijo naslova — lahko jih shranite v svoje operativne dnevnike.