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.
Waar het staat
Section titled “Waar het staat”| Product | Code | Message | Details |
|---|---|---|---|
| LEO-familie, envelop | context.error.code | context.error.message | context.error.details |
LEO-familie, /models en /chat/completions | error.code | error.message | error.details |
| IRMA | error | message | details |
| ORDO | error | message | details |
In de LEO-familie is een fout een gewone envelop met data: null. Dit antwoord komt van productie:
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.
Veelvoorkomende codes
Section titled “Veelvoorkomende codes”| HTTP | Code | Betekenis |
|---|---|---|
| 401 | missing_api_key | Geen Authorization-header |
| 401 | invalid_api_key | Onbekende of ongeldige sleutel |
| 401 | api_key_revoked | De sleutel is ingetrokken |
| 401 | api_key_expired | De sleutel is verlopen |
| 401 | key_environment_mismatch | Een live-sleutel op staging, of een testsleutel op productie |
| 403 | insufficient_scope | De scope ontbreekt; zie details.required_scope |
| 403 | ip_not_allowed | Dit IP-adres staat niet op de lijst van de sleutel |
| 403 | chat_requires_user_token | Chat vraagt een token van een gebruiker, geen servicesleutel |
| 403 | approval_required | Een goedkeuring is nodig |
| 403 | forbidden_for_agents | Alleen een mens in de app |
| 404 | unknown_operation | Deze operatie bestaat niet (of staat nog niet op deze omgeving) |
| 409 | idempotency_request_in_progress | Dezelfde Idempotency-Key loopt nog |
| 422 | idempotency_key_reused | Dezelfde Idempotency-Key met een andere body |
| 422 | validation_error | Een ongeldige waarde |
| 422 | scope_not_available | Deze scope is nog niet uit te geven |
| 429 | rate_limited | Limiet bereikt; volg Retry-After |
| 503 | service_unavailable | Tijdelijk niet beschikbaar; volg Retry-After |
De volledige lijst per operatie staat in de referentie, onder Antwoorden.
Opnieuw proberen
Section titled “Opnieuw proberen”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.