Utvecklarreferens

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ältBeskrivning
codeStabil, maskinläsbar felkod. Koder byter aldrig namn, så du kan tryggt grena på dem.
messageLä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.
statusHTTP-statuskoden, upprepad i svarskroppen för loggar och köer.
retryableOm samma begäran kan lyckas om du försöker igen senare.
request_idUnik begärans-ID. Motsvarar headern X-Request-Id.
docs_urlLänk till det avsnitt i dokumentationen som förklarar felet.
suggestionValfri ledtråd om hur du rättar begäran.
detailsValfri strukturerad kontext, till exempel tillåtna metoder eller den ogiltiga parametern.
retry_afterValfritt 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.

KodHTTP-statusTypKan göras omBeskrivning
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 är true. Vid validerings-, autentiserings- och behörighetsfel ska du först rätta begäran.
  • Om retry_after eller headern Retry-After finns 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-Key nä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.