Fel och återhämtning
På den här sidan
Hantera fel utan att gissa om en skrivning slutfördes.
Behåll säkert supportunderlag
Bevara säker requestId eller X-Request-Id för support, tillsammans med operation och tidpunkt. Håll nyckelhemligheter, sökandeuppgifter och dokument-URL:er utanför loggar.
Hantera HTTP-fel
| Svar | Nästa åtgärd |
|---|---|
| 400 / 422 | Rätta anropet med hjälp av operationens schema och felkod; upprepa inte ogiltig indata oförändrad. |
| 401 | Stanna och be administratören kontrollera den saknade, ogiltiga, utgångna eller återkallade nyckeln. |
| 403 | Kontrollera nödvändig behörighet och företagsavgränsning. Begär inte automatiskt bredare åtkomst. |
| 404 | Kontrollera returnerat resurs-ID och uppgift. Ett ändrat ID ger inte åtkomst till ett annat företags resurs. |
| 409 | Läs felkoden och aktuell version av resurs/förhandsgranskning/formulär. Lös konflikten före en ny ändring. |
| 410 | Följ operationens betydelse: en utgången synkroniseringscursor kräver ny fullständig synkronisering; en borttagen ansökan får inte återskapas genom ett gammalt återförsök. |
| 429 | Respektera Retry-After när det anges samt X-RateLimit-Reset; använd begränsad väntan mellan försök med slumpmässig spridning. |
| Tidsgräns / tillfällig 5xx | Behandla skrivresultatet som okänt. Läs tillbaka med känt ID eller återspela med ursprunglig nyckel inom 24-timmarsfönstret, med begränsad väntan mellan försök. Skapa ingen ny operation. |
Återställ ett okänt skrivresultat
Efter ett förlorat svar: läs tillbaka resursen eller operationen om dess returnerade ID är känt. Om inget returnerat ID är känt, upprepa det identiska anropet med ursprunglig Idempotency-Key och ursprunglig API-nyckel inom 24 timmar från första försöket. Om fönstret har löpt ut eller säker återläsning/återspelning saknas, stanna och stäm av resultatet; varken en utgången nyckel eller en ny nyckel garanterar att skrivningen inte körs igen. Förhandsgranskningar, jobb och deras historik förblir bundna till nyckeln som skapade dem.
Rotera och avveckla nycklar
Vid rotation skapar du en ersättningsnyckel med samma eller snävare behörigheter, tar den i bruk i integrationen och verifierar en autentiserad läsning. Före återkallning av den gamla nyckeln slutför eller stämmer du av dess utestående förhandsgranskningar och jobb med den gamla nyckeln. En ersättningsnyckel ärver inte deras jobb-ID:n eller historik. Återkalla sedan den gamla nyckeln. Administratören använder Settings → API & agents eller dess autentiserade kontrollplan /api/v1/settings/api-keys. En företagsintegrationsnyckel är inte en administratörssession. Nyckel-ID:n är icke-hemliga referenser, inte autentiseringsuppgifter; den råa nyckeln kan inte hämtas senare. Verifiera att den avvecklade nyckeln avvisas.
Använd den publicerade kontraktsversionen
Använd API-versionen och livscykeln i API-referensen, varje operations scheman samt eventuell nödvändig formulär- eller resursversion när en integration uppdateras. Bevara opaka versioner oförändrade och lås en godkänd MCP-release. Händelsenamn kommer från samma katalog som API:t; ankomstordning och en produktversion ersätter inte aktuell återläsning av resursen.