Foutcodes

Foutcodes

Gestructureerde fouten

Elke API-fout geeft dezelfde JSON-structuur terug: een object error met een stabiele code, een leesbaar message, het type en de HTTP-status, de aanduiding of het retryable is, de request_id en een docs_url. De request_id komt altijd overeen met de responseheader X-Request-Id, dus vermeld deze wanneer u contact opneemt met support.

{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Ongeldig domeinformaat",
    "suggestion": "Gebruik een registreerbaar domein zoals example.com",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}

Foutvelden

Veelvoorkomende foutcodes

Dit zijn de codes die de meeste clients moeten afhandelen. Sommige endpoints geven specifiekere codes terug die dezelfde regels volgen; de volledige lijst met status, type en gedrag bij opnieuw proberen staat in de OpenAPI-specificatie onder x-domscan-error-codes. RATE_LIMIT_EXCEEDED wordt nog steeds geaccepteerd als alias van RATE_LIMITED.

Richtlijnen voor opnieuw proberen

• Probeer het alleen opnieuw wanneer retryable de waarde true heeft. Bij validatie-, authenticatie- en rechtenfouten moet u eerst het verzoek corrigeren.
• Als retry_after of de header Retry-After aanwezig is, wacht dan minstens dat aantal seconden voor de volgende poging.
• Gebruik anders exponentiële backoff met jitter, bijvoorbeeld 1, 2, 4 en 8 seconden, en stop na een paar pogingen.
• Stuur bij het aanmaken van batches en jobs een header Idempotency-Key mee, zodat een herhaald verzoek nooit een dubbele job aanmaakt.
• Bij andere POST-verzoeken die credits in rekening brengen, zorgt een Idempotency-Key-header ervoor dat een nieuwe poging het opgeslagen antwoord teruggeeft in plaats van opnieuw te rekenen.

Compatibiliteit

Sinds 10 oktober 2026 gebruikt elk endpoint dit formaat. Velden die sommige endpoints al teruggaven, zoals credits_remaining, purchase_url, login_url, success of meta, blijven tijdens een compatibiliteitsperiode behouden, zodat bestaande integraties blijven werken. Lees foutdetails in nieuwe code uit het object error.