Foutcatalogus¶

Elke fout in application/problem+json heeft een type dat zegt welke soort fout het is. Deze pagina somt de soorten op: de status waarmee elke soort binnenkomt, wanneer ze optreedt en wat je eraan doet. Het foutformaat zelf staat op Fouten, paginering en herhalen.

Zo lees je type¶

Publiceert je omgeving deze handleiding, dan is type het adres van de soort op deze pagina:

{
  "type": "https://docs.example.nl/en/reference/errors/#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The prompt was not found.",
  "request_id": "req_5Tn8..."
}

• Vergelijk type als één hele tekenreeks als je het adres van de handleiding van je omgeving kent, en vergelijk anders het deel na #. Dat deel is de soort en is in elke omgeving hetzelfde; het deel ervoor is het adres van de handleiding van de omgeving die antwoordde.
• Een soort verandert nooit: niet met een nieuwe versie, niet met de taal van je verzoek en niet als de tekst van title of detail verandert. Beslis op type en status, en op reason_code waar een soort hieronder er een noemt, en toon detail aan mensen. Een reason_code kan er een waarde bij krijgen: behandel een waarde die je niet kent als een gewoon probleem van zijn status.
• Het adres wijst altijd naar de Engelse pagina. Deze Nederlandse pagina heeft dezelfde soorten onder dezelfde ankers: vervang /en/ in het adres door /nl/.
• Een omgeving die geen handleiding publiceert, antwoordt bij elke fout "type": "about:blank". about:blank noemt geen soort: val terug op status.
• Een antwoord dat de gateway vóór Core zelf schrijft, draagt zijn soort op dezelfde manier waar de omgeving haar handleiding publiceert, en about:blank waar ze dat niet doet. Dat geldt voor request-timeout, request-header-fields-too-large, bad-gateway en gateway-timeout, die alleen de gateway geeft, en voor elke andere soort wanneer de gateway die zelf geeft. Zo'n antwoord heeft geen X-Request-Id-header.
• De vijf modelroutes antwoorden met fouten in de vorm van de leverancier, behalve de antwoorden die daar staan. In die vorm is type het woord van de leverancier (invalid_request_error) en geen van de soorten hieronder. De uitzonderingen zijn problem+json zoals overal, met een type zoals op elke andere route.

De soorten¶

bad-request¶

• Status: 400
• Wanneer: Het verzoek kan niet worden uitgevoerd zoals het is verstuurd: het HTTP-verzoek zelf klopt niet, of een login waarbij de persoon zelf inlogt keerde terug met een toestand die niet meer geldig is.
• Wat je doet: Corrigeer het verzoek. Mislukte het inloggen, laat de persoon het dan vanaf het begin opnieuw doen.

unauthenticated¶

• Status: 401, met WWW-Authenticate: Bearer
• Wanneer: De sleutel of het token ontbreekt, is onjuist, verlopen of ingetrokken.
• Wat je doet: Controleer de secret van de API-sleutel, of meld je opnieuw aan voor een nieuw token. Herhalen met dezelfde gegevens geeft hetzelfde antwoord.

forbidden¶

• Status: 403
• Wanneer: Je bent herkend, maar mag dit niet, en de reden is geen beleid (policy-denied): de bewerking staat bijvoorbeeld niet open voor jouw rol, of de organisatie of een organisatie erboven is opgeschort. Een opschorting draagt "reason_code": "organisation_suspended" en het detail The organisation this key belongs to is suspended. Ask its administrator.; op de Responses-routes staat hetzelfde woord in error.code. Een subjecttoken wordt ook zo geweigerd op een route die hij niet mag bereiken, en bij een verzoek dat een andere persoon noemt dan de zijne: A subject token may not reach this route.
• Wat je doet: Lees detail. Gebruik gegevens die dit wel mogen. Bij organisation_suspended is je sleutel in orde: vraag wie de organisatie beheert om haar weer te activeren, en probeer het tot dan niet opnieuw.

policy-denied¶

• Status: 403
• Wanneer: Het beleid van je sleutel, of van de organisatie waar hij bij hoort, verbiedt deze handeling: een model, een tool, een host of een resource die het beleid niet toestaat. Het is ook het antwoord als je een ding mag zien maar de acties van een regel de persoon het niet laten gebruiken, wijzigen of verwijderen, en als aanmaken, hernoemen of nieuwe labels een ding een naam of labels zou geven die geen write-regel toestaat. Er wordt niets geschreven.
• Wat je doet: Lees detail; daar staat wat is geweigerd. Pas het verzoek aan, of laat een beheerder het beleid aanpassen.

not-found¶

• Status: 404
• Wanneer: De resource bestaat niet, is van een andere organisatie, of ligt buiten het bereik van je sleutel: de capability staat uit of het beleid noemt de resource niet. Het antwoord is in alle drie de gevallen hetzelfde.
• Wat je doet: Controleer met GET /key wat je sleutel bereikt, en daarna het id en het pad.

method-not-allowed¶

• Status: 405
• Wanneer: Het pad bestaat, maar niet met deze HTTP-methode.
• Wat je doet: Zoek de bewerking op in de API-referentie.

request-timeout¶

• Status: 408, beantwoord door de gateway
• Wanneer: Het verzoek was, met de body erbij, na 300 seconden nog niet volledig aangekomen (tijdslimiet).
• Wat je doet: Stuur een kleinere body, of verstuur hem over een snellere verbinding.

conflict¶

• Status: 409
• Wanneer: De huidige toestand weigert het verzoek: een naam die al bestaat, een stap die niet volgt uit de toestand van de resource, een organisatie die nog wordt ingericht of verwijderd, een datastorerecord waarvan het unieke veld een waarde heeft die een ander record al heeft (detail noemt het veld), of een schrijfactie waarvan If-Match een versie noemt die niet meer de opgeslagen versie is. Die laatste draagt "reason_code": "stale_version" in de body; de andere oorzaken dragen geen reason_code.
• Wat je doet: Lees detail. Lees de resource opnieuw en beslis op haar huidige toestand; is de organisatie nog niet klaar, probeer het dan later opnieuw. Bij stale_version lees je opnieuw en herhaal je je wijziging op wat nu is opgeslagen (sleutels).

still-referenced¶

• Status: 409, met een lijst conflicts
• Wanneer: Je verwijdert iets dat nog in gebruik is, zoals een tool die een agent noemt.
• Wat je doet: Haal elk gebruik in conflicts weg en verwijder daarna opnieuw. Elk item draagt een reason_code uit een vaste lijst waarop je client kan schakelen (iets verwijderen dat nog in gebruik is).

precondition-failed¶

• Status: 412
• Wanneer: Een schrijfactie noemt in een header de toestand die ze verwacht, en wat is opgeslagen is nu niet in die toestand: If-Match draagt een ETag die het record niet meer heeft, omdat iemand het sinds je het las heeft geschreven of verwijderd, of If-None-Match: * vraagt een record aan te maken dat al bestaat. Er is niets geschreven.
• Wat je doet: Lees het record opnieuw, beslis op wat het nu bevat en stuur de schrijfactie met de nieuwe ETag (datastores). Is bij een schrijfactie die alleen mag aanmaken de sleutel bezet, lees dan het record onder die sleutel en vervang het met zijn ETag, of kies een andere sleutel.

content-too-large¶

• Status: 413
• Wanneer: De body of de upload is groter dan de route aanneemt. Voor de meeste routes geeft de gateway dit antwoord; voor modelaanroepen en uploads antwoordt Core, en noemt de limiet waar dat kan.
• Wat je doet: Stuur minder. Hetzelfde verzoek wordt opnieuw geweigerd.

unsupported-media-type¶

• Status: 415
• Wanneer: De body is geen soort bestand dat deze route aanneemt. Core beslist op de bytes zelf, niet op de header Content-Type.
• Wat je doet: Stuur een van de typen die detail noemt.

range-not-satisfiable¶

• Status: 416, met Content-Range: bytes */<grootte>
• Wanneer: Een download vroeg om een Range die voorbij het einde van het bestand begint.
• Wat je doet: Lees de grootte uit Content-Range en vraag een bereik daarbinnen.

unprocessable-content¶

• Status: 422, meestal met een lijst errors
• Wanneer: Het verzoek is begrepen, en een of meer waarden erin zijn geweigerd: een ontbrekend veld, een verkeerd type, of een waarde die Core niet aanneemt.
• Wat je doet: Corrigeer elk veld in errors (foutformaat). Zonder lijst lees je detail. Een schrijfactie die de schrijffunctie van een datastore weigerde, draagt de reden in refusal. Een schrijfactie waarover de functie niets besliste, draagt error_code: trapped, fuel_exhausted, memory_exceeded, timeout, invalid_arguments, invalid_response, of executor_failed als de functie helemaal niet kon draaien (verwijderd, geen gepubliceerde versie met dat nummer, haar laatste versie leest of schrijft nu, of op dat moment geen ruimte om haar te draaien). Een tool die op een computer draait, genoemd waar je installatie er geen heeft voor je organisatie, draagt "reason_code": "computer_not_configured" in de body, met het detail This tool is not configured on this deployment.; op de Responses-routes is hetzelfde woord error.code. Niets in het verzoek lost dat op.

contradicts-stored¶

• Status: 422, met een lijst conflicts
• Wanneer: Het verzoek is goed gevormd, maar iets dat al is opgeslagen spreekt het tegen: bijvoorbeeld een smaller vocabulaire terwijl sleutels nog een label gebruiken dat zou vervallen.
• Wat je doet: Pas aan wat je stuurt, of pas eerst elke rij in conflicts aan. Alle tegenspraken staan er in één keer, tot en met de eerste honderd. Elke rij draagt een reason_code; de enige waarde die een 422 nu gebruikt is outside_vocabulary.

too-many-requests¶

• Status: 429, soms met Retry-After
• Wanneer: Je verstuurt verzoeken sneller dan de omgeving toestaat; je organisatie, of één persoon erin, houdt al zoveel eventstreams open als mag; of je organisatie heeft al zoveel workflowruns open, of zoveel workflowtriggers, als de omgeving toestaat.
• Wat je doet: Wacht zo lang als Retry-After zegt als die er is, en herhaal anders met oplopende wachttijden. Sluit een stream die je niet meer leest, laat een run eindigen, of verwijder een trigger.

usage-cap-reached¶

• Status: 429, met Retry-After
• Wanneer: De maandlimiet van je organisatie of van je sleutel is bereikt. detail zegt welke.
• Wat je doet: Retry-After bevat de seconden tot de limiet opnieuw begint; eerder herhalen geeft hetzelfde antwoord. Laat de limiet verhogen als het werk niet kan wachten (je maandlimiet).

request-header-fields-too-large¶

• Status: 431, beantwoord door de gateway
• Wanneer: De headers van het verzoek zijn samen groter dan de gateway aanneemt.
• Wat je doet: Stuur minder of kortere headers.

internal-error¶

• Status: 500
• Wanneer: Er ging iets mis dat Core niet voorzag. De body zegt nooit wat.
• Wat je doet: Bewaar het request_id en meld de fout als die blijft terugkomen. Kijk eerst wat je veilig kunt herhalen.

bad-gateway¶

• Status: 502, beantwoord door de gateway
• Wanneer: De gateway kreeg geen bruikbaar antwoord van Core, bijvoorbeeld tijdens een herstart.
• Wat je doet: Herhaal met oplopende wachttijden, binnen wat je veilig kunt herhalen.

service-unavailable¶

• Status: 503, soms met Retry-After
• Wanneer: Iets wat Core nodig heeft is even onbereikbaar, een ander verzoek wijzigt op dat moment hetzelfde, of de gateway weert verzoeken omdat hij overbelast is.
• Wat je doet: Wacht zo lang als Retry-After zegt als die er is, en herhaal anders met oplopende wachttijden.

gateway-timeout¶

• Status: 504, beantwoord door de gateway
• Wanneer: Core antwoordde niet binnen de tijd die de route toestaat.
• Wat je doet: Het verzoek kan toch zijn uitgevoerd. Lees de resource voordat je opnieuw verstuurt, of herhaal met een idempotentiesleutel.