Ga naar inhoud

Fouten

Elke fout heeft drie dingen: een vaste string-code om op te programmeren, een leesbare message en, waar het iets toevoegt, details. Programmeer op de code, nooit op de message.

ProductCodeMessageDetails
LEO-familie, envelopcontext.error.codecontext.error.messagecontext.error.details
LEO-familie, /models en /chat/completionserror.codeerror.messageerror.details
IRMAerrormessagedetails
ORDOerrormessagedetails

In de LEO-familie is een fout een gewone envelop met data: null. Dit antwoord komt van productie:

Terminal window
curl -s https://api.prudai.com/v1/sources
{
"data": null,
"context": {
"request_id": "req_...",
"error": {
"message": "A Bearer API key is required.",
"type": "authentication_error",
"code": "missing_api_key",
"param": null,
"request_id": "req_..."
}
},
"completeness": { "total": 0, "returned": 0, "truncated": false },
"notIncluded": [],
"provenance": {},
"next": []
}

/models en /chat/completions houden de OpenAI-vorm { "error": { ... } }, zodat de OpenAI-SDK’s hun gewone fouten geven.

Bij IRMA en ORDO is error zelf de string-code:

{ "error": "insufficient_scope", "message": "...", "details": { "required_scope": "..." } }

De CLI maakt er in alle gevallen één vorm van: { error, message, exitCode, ...details }. Zie CLI.

HTTPCodeBetekenis
401missing_api_keyGeen Authorization-header
401invalid_api_keyOnbekende of ongeldige sleutel
401api_key_revokedDe sleutel is ingetrokken
401api_key_expiredDe sleutel is verlopen
401key_environment_mismatchEen live-sleutel op staging, of een testsleutel op productie
403insufficient_scopeDe scope ontbreekt; zie details.required_scope
403ip_not_allowedDit IP-adres staat niet op de lijst van de sleutel
403chat_requires_user_tokenChat vraagt een token van een gebruiker, geen servicesleutel
403approval_requiredEen goedkeuring is nodig
403forbidden_for_agentsAlleen een mens in de app
404unknown_operationDeze operatie bestaat niet (of staat nog niet op deze omgeving)
409idempotency_request_in_progressDezelfde Idempotency-Key loopt nog
422idempotency_key_reusedDezelfde Idempotency-Key met een andere body
422validation_errorEen ongeldige waarde
422scope_not_availableDeze scope is nog niet uit te geven
429rate_limitedLimiet bereikt; volg Retry-After
503service_unavailableTijdelijk niet beschikbaar; volg Retry-After

De volledige lijst per operatie staat in de referentie, onder Antwoorden.

Elk antwoord heeft een X-Request-Id; noem die bij support. Probeer opnieuw bij 429 en 503, met oplopende wachttijd, en volg Retry-After. Gebruik bij een herhaalde schrijfactie dezelfde Idempotency-Key.