Gidsen
Fouten en herstel
Gebruik stabiele foutcodes, gestructureerde details en verzoek-ID’s om te bepalen wat je moet corrigeren en wanneer je opnieuw probeert.
Een vaste foutenvelop
Fouten bevatten een error-object met type, code, message, request_id en optioneel details. Baseer de logica op de HTTP-status en stabiele code; de melding is voor diagnose. Elk antwoord bevat ook X-Request-Id. Bewaar die identificatie wanneer je een probleem meldt en houd sleutels en gevoelige payloads uit je logs.
{
"error": {
"type": "validation_error",
"code": "validation_failed",
"message": "The supplied field is not available.",
"details": { "unknown": ["nname"], "nearest": { "nname": ["name"] } },
"request_id": "4d85a25f-d510-41f5-b228-32a875670fd0"
}
}Het juiste herstel kiezen
Corrigeer ongeldige invoer en toegangsproblemen voordat je opnieuw probeert. Een 404 geldt ook voor records in een andere werkruimte of onzichtbaar voor de eigenaar.
| Status | Codes | Herstel |
|---|---|---|
| 400 | invalid_request | Corrigeer JSON, parameters, filters of cursorinstellingen. |
| 401 | invalid_api_key, expired_api_key, key_assurance_stale | Controleer geheim, vervaldatum en MFA; vervang zo nodig de sleutel. |
| 403 | ip_not_allowed, permission_denied, plan_upgrade_required, insufficient_scope, feature_unavailable, forbidden | Controleer server-IP, lidmaatschap, rol, abonnement, scope en beschikbaarheid. |
| 404 | not_found, unknown_resource, route_not_found | Controleer pad, ID’s en zichtbaarheid van de eigenaar. |
| 405 | method_not_allowed | Gebruik een methode uit Allow; sommige resources zijn alleen leesbaar. |
| 409 | conflict, idempotency_key_in_use | Los het conflict op of wacht voor hetzelfde idempotente verzoek. |
| 413 | payload_too_large | Verklein de body tot maximaal 1 MiB. |
| 422 | validation_failed, idempotency_key_reused | Corrigeer velden/types of gebruik een nieuwe key voor een andere operatie. |
| 429 | rate_limited, quota_exceeded | Respecteer Retry-After; controleer limieten en quotumreset. |
| 500 / 503 | internal_error, service_unavailable | Gebruik begrensde backoff en behoud de idempotency-key van de wijziging. |
Details gebruiken, niet raden
Validatiedetails kunnen unknown, nearest en alternatives bevatten met te corrigeren velden of opties. Pagineringsfouten kunnen max_page geven; quotumfouten resets_at; databasevalidatie sqlstate en een relevante hint. Beschrijf de resource opnieuw als het werkruimteschema is veranderd.
Begrensd opnieuw proberen
Gebruik bij tijdelijke fouten een beperkt aantal retries met exponentiële backoff en jitter. Respecteer Retry-After wanneer aanwezig. Herhaal een 400, 401, 403 of validatiefout niet automatisch. Behoud hetzelfde exacte verzoek en dezelfde idempotency-key bij schrijfverzoeken en controleer onzekere uitkomsten voordat je opnieuw schrijft.