> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/nl/docs/error-codes

# Foutcodes

Bekijk de API-documentatie voor Foutcodes, aanvraagparameters, responsvelden, codevoorbeelden en foutafhandeling voor DomScan-integraties.

### 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.

```json
{
  "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

| Veld | Beschrijving |
| --- | --- |
| `code` | Stabiele, machineleesbare foutcode. Codes worden nooit hernoemd, dus u kunt er veilig op vertakken. |
| `message` | Leesbare uitleg van de fout. De formulering kan veranderen, dus verwerk deze niet programmatisch. |
| `type` | Brede foutcategorie, zoals `validation_error`, `authentication_error` of `rate_limit_error`. |
| `status` | De HTTP-statuscode, herhaald in de body voor logs en wachtrijen. |
| `retryable` | Of hetzelfde verzoek kan slagen als u het later opnieuw probeert. |
| `request_id` | Unieke verzoek-ID. Komt overeen met de header `X-Request-Id`. |
| `docs_url` | Link naar het documentatiegedeelte dat deze fout toelicht. |
| `suggestion` | Optionele tip om het verzoek te corrigeren. |
| `details` | Optionele gestructureerde context, zoals de toegestane methoden of de ongeldige parameter. |
| `retry_after` | Optioneel aantal seconden om te wachten voordat u het opnieuw probeert. Wordt ook verzonden als de header `Retry-After`. |

### 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`.

| Code | HTTP-status | Type | Opnieuw te proberen | Beschrijving |
| --- | --- | --- | --- | --- |
| `BAD_REQUEST` | 400 | `validation_error` | Nee | Ontbrekende of ongeldige parameters |
| `MISSING_PARAMETER` | 400 | `validation_error` | Nee | Een verplichte parameter ontbreekt |
| `INVALID_PARAMETER` | 400 | `validation_error` | Nee | Een parameter heeft een ongeldige waarde |
| `INVALID_JSON` | 400 | `validation_error` | Nee | De body van het verzoek is geen geldige JSON |
| `INVALID_DOMAIN` | 400 | `validation_error` | Nee | Ongeldige domeinindeling |
| `UNSUPPORTED_TLD` | 400 | `validation_error` | Nee | TLD niet ondersteund |
| `SUBDOMAIN_NOT_SUPPORTED` | 400 | `validation_error` | Nee | Dit endpoint accepteert registreerbare domeinen, geen subdomeinen |
| `VALIDATION_ERROR` | 422 | `validation_error` | Nee | Het verzoek is correct opgebouwd, maar kan niet worden verwerkt |
| `AUTH_REQUIRED` | 401 | `authentication_error` | Nee | Er is geen API-sleutel of sessie opgegeven |
| `INVALID_API_KEY` | 401 | `authentication_error` | Nee | De API-sleutel is ongeldig of is ingetrokken |
| `INSUFFICIENT_CREDITS` | 402 | `credits_error` | Nee | Uw account heeft niet genoeg credits voor dit verzoek |
| `FORBIDDEN` | 403 | `permission_error` | Nee | U hebt geen toestemming voor deze actie |
| `NOT_FOUND` | 404 | `not_found_error` | Nee | Het endpoint of de resource bestaat niet |
| `METHOD_NOT_ALLOWED` | 405 | `request_error` | Nee | Het endpoint bestaat, maar accepteert deze HTTP-methode niet. De header `Allow` vermeldt de ondersteunde methoden. |
| `CONFLICT` | 409 | `conflict_error` | Nee | Het verzoek botst met de huidige staat van de resource |
| `IDEMPOTENCY_CONFLICT` | 409 | `conflict_error` | Nee | De idempotentiesleutel is al gebruikt met een ander verzoek |
| `IDEMPOTENCY_KEY_REUSED` | 422 | `validation_error` | Nee | Deze `Idempotency-Key` is de afgelopen 24 uur al gebruikt voor een ander verzoek. Gebruik een nieuwe sleutel voor een nieuw verzoek. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | `conflict_error` | Ja | Een verzoek met deze `Idempotency-Key` loopt nog. Probeer het zo opnieuw om het opgeslagen antwoord te ontvangen. |
| `RATE_LIMITED` | 429 | `rate_limit_error` | Ja | Te veel verzoeken |
| `INTERNAL` | 500 | `api_error` | Nee | Onverwachte serverfout. Neem contact op met support en vermeld het verzoek-ID als de fout aanhoudt. |
| `UPSTREAM_ERROR` | 502 | `upstream_error` | Ja | Een upstreambron gaf een onbruikbaar antwoord terug |
| `UPSTREAM_UNAVAILABLE` | 503 | `upstream_error` | Ja | Een upstreambron is tijdelijk niet beschikbaar |
| `SERVICE_UNAVAILABLE` | 503 | `upstream_error` | Ja | De dienst is tijdelijk niet beschikbaar |
| `TIMEOUT` | 504 | `timeout_error` | Ja | Een upstreambron of register reageerde niet op tijd |

### 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`.