Felkoder
Utforska API-dokumentationen för Felkoder, anropsparametrar, svarsfält, kodexempel och felhantering för DomScan-integrationer.
Felkoder
Strukturerade fel
Varje API-fel returnerar samma JSON-struktur: ett error-objekt med en stabil code, ett läsbart message, dess type och HTTP-status, uppgift om det är retryable, request_id och en docs_url. request_id motsvarar alltid svarsheadern X-Request-Id, så ta med det när du kontaktar supporten.
{
"error": {
"code": "INVALID_DOMAIN",
"message": "Ogiltigt domänformat",
"suggestion": "Använd en registrerbar domän som example.com",
"type": "validation_error",
"status": 400,
"retryable": false,
"request_id": "m5x7k2p-a9f3",
"docs_url": "https://domscan.net/docs/check-availability"
}
}
Felfält
| Fält | Beskrivning |
|---|---|
code | Stabil, maskinläsbar felkod. Koder byter aldrig namn, så du kan tryggt grena på dem. |
message | Läsbar förklaring av felet. Formuleringen kan ändras, så tolka den inte i kod. |
type | Övergripande felkategori, till exempel validation_error, authentication_error eller rate_limit_error. |
status | HTTP-statuskoden, upprepad i svarskroppen för loggar och köer. |
retryable | Om samma begäran kan lyckas om du försöker igen senare. |
request_id | Unik begärans-ID. Motsvarar headern X-Request-Id. |
docs_url | Länk till det avsnitt i dokumentationen som förklarar felet. |
suggestion | Valfri ledtråd om hur du rättar begäran. |
details | Valfri strukturerad kontext, till exempel tillåtna metoder eller den ogiltiga parametern. |
retry_after | Valfritt antal sekunder att vänta innan du försöker igen. Skickas även som headern Retry-After. |
Vanliga felkoder
Det här är de koder som de flesta klienter behöver hantera. Vissa endpoints returnerar mer specifika koder som följer samma regler. Den fullständiga listan med status, typ och omförsöksbeteende finns i OpenAPI-specifikationen under x-domscan-error-codes. RATE_LIMIT_EXCEEDED godtas fortfarande som alias för RATE_LIMITED.
| Kod | HTTP-status | Typ | Kan göras om | Beskrivning |
|---|---|---|---|---|
BAD_REQUEST |
400 | validation_error |
Nej | Parametrar saknas eller är ogiltiga |
MISSING_PARAMETER |
400 | validation_error |
Nej | En obligatorisk parameter saknas |
INVALID_PARAMETER |
400 | validation_error |
Nej | En parameter har ett ogiltigt värde |
INVALID_JSON |
400 | validation_error |
Nej | Begärans innehåll är inte giltig JSON |
INVALID_DOMAIN |
400 | validation_error |
Nej | Ogiltigt domänformat |
UNSUPPORTED_TLD |
400 | validation_error |
Nej | TLD stöds inte |
SUBDOMAIN_NOT_SUPPORTED |
400 | validation_error |
Nej | Den här endpointen accepterar registrerbara domäner, inte underdomäner |
VALIDATION_ERROR |
422 | validation_error |
Nej | Begäran är korrekt uppbyggd men kan inte behandlas |
AUTH_REQUIRED |
401 | authentication_error |
Nej | Ingen API-nyckel eller session angavs |
INVALID_API_KEY |
401 | authentication_error |
Nej | API-nyckeln är ogiltig eller har återkallats |
INSUFFICIENT_CREDITS |
402 | credits_error |
Nej | Ditt konto har inte tillräckligt med krediter för den här begäran |
FORBIDDEN |
403 | permission_error |
Nej | Du har inte behörighet att utföra den här åtgärden |
NOT_FOUND |
404 | not_found_error |
Nej | Endpointen eller resursen finns inte |
METHOD_NOT_ALLOWED |
405 | request_error |
Nej | Endpointen finns men accepterar inte den här HTTP-metoden. Headern Allow listar de metoder som stöds. |
CONFLICT |
409 | conflict_error |
Nej | Begäran står i konflikt med resursens nuvarande tillstånd |
IDEMPOTENCY_CONFLICT |
409 | conflict_error |
Nej | Idempotensnyckeln har redan använts med en annan begäran |
IDEMPOTENCY_KEY_REUSED |
422 | validation_error |
Nej | Denna Idempotency-Key har redan använts med en annan begäran under de senaste 24 timmarna. Använd en ny nyckel för en ny begäran. |
IDEMPOTENCY_IN_PROGRESS |
409 | conflict_error |
Ja | En begäran med denna Idempotency-Key körs fortfarande. Försök igen om en stund för att få det lagrade svaret. |
RATE_LIMITED |
429 | rate_limit_error |
Ja | För många begäranden |
INTERNAL |
500 | api_error |
Nej | Oväntat serverfel. Kontakta supporten med begärans-ID:t om det kvarstår. |
UPSTREAM_ERROR |
502 | upstream_error |
Ja | En uppströmskälla returnerade ett oanvändbart svar |
UPSTREAM_UNAVAILABLE |
503 | upstream_error |
Ja | En uppströmskälla är tillfälligt otillgänglig |
SERVICE_UNAVAILABLE |
503 | upstream_error |
Ja | Tjänsten är tillfälligt otillgänglig |
TIMEOUT |
504 | timeout_error |
Ja | En uppströmskälla eller ett register svarade inte i tid |
Riktlinjer för omförsök
- Försök igen endast när
retryableärtrue. Vid validerings-, autentiserings- och behörighetsfel ska du först rätta begäran. - Om
retry_aftereller headernRetry-Afterfinns ska du vänta minst så många sekunder före nästa försök. - Annars använder du exponentiell backoff med jitter, till exempel 1, 2, 4 och 8 sekunder, och slutar efter några försök.
- Skicka headern
Idempotency-Keynär du skapar batchar och jobb, så att en upprepad begäran aldrig skapar ett dubblettjobb. - För andra POST-begäranden som debiterar krediter gör en
Idempotency-Key-header att ett nytt försök returnerar det lagrade svaret i stället för att debitera igen.
Kompatibilitet
Sedan den 10 oktober 2026 använder alla endpoints det här formatet. Fält som vissa endpoints redan returnerade, till exempel credits_remaining, purchase_url, login_url, success eller meta, behålls under en kompatibilitetsperiod så att befintliga integrationer fortsätter fungera. Läs feldetaljer från objektet error i ny kod.