Feil og gjenoppretting

Bruk stabile feilkoder til å avgjøre om du skal rette, vente eller prøve på nytt.

Hva du skal gjøre

La programmet reagere på HTTP-status og error.code, ikke den menneskelesbare error.message.
En 401 krever gyldig autentisering; 403 krever endringer i tilgang eller abonnement; 409 krever kontroll av operasjonen eller ressursversjonen som er i konflikt.

Tilgang nektet og nye forsøk

401: 401 betyr ikke alltid at tokenet er utløpt. Hvis det er utløpt, hent et nytt og gjenta lesingen høyst én gang. Hvis henting av tokenet gir 401, kontroller nøkkelen og stopp automatiske forsøk.
403: Ved 403 må du kontrollere rettigheter, IP-begrensninger og abonnement. Et nytt token gjenoppretter ikke tilbakekalt tilgang.

Autentisering

Regler for nye forsøk

Bruk et begrenset antall nye forsøk med økende og tilfeldig ventetid ved midlertidige feil.
Følg Retry-After når headeren er oppgitt.
Hvis en skriveoperasjon får tidsavbrudd, kan resultatet være ukjent: behold samme Idempotency-Key og uendret forespørsel når du gjentar den logiske operasjonen.
Katalogen nedenfor forklarer alle publiserte feilkoder.

Trygge skriveoperasjoner

Forespørselsgrenser

422 / 409

For priser gir et ugyldig valutaformat eller en ugyldig presisjon for beløpet 422 request.validation_failed.
En gyldig valutakode som ikke samsvarer med den valgte prislisten, gir 409 resource.version_conflict.
Kontroller konteksten og versjonene før du prøver igjen.

Feilkatalog

400request.malformedForespørselen kan ikke tolkes.

Hva du skal gjøre: Kontroller JSON-syntaks, URL-koding og forespørselens struktur.
Regler for nye forsøk: Prøv på nytt etter å ha rettet forespørselen.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI-nøkkelen eller tilgangstokenet er ugyldig, utløpt eller tilbakekalt.

Hva du skal gjøre: Kontroller butikkens URL og legitimasjonen. Hent et nytt token med en aktiv API-nøkkel.
Regler for nye forsøk: Prøv på nytt etter å ha rettet autentiseringen; unngå gjentatte forespørsler med ugyldige tokens.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredDen nødvendige Authorization-headeren mangler, eller autentiseringsmetoden er feil.

Hva du skal gjøre: Bruk ApiKey når du ber om et token, og Bearer for ressursoperasjoner.
Regler for nye forsøk: Prøv på nytt etter å ha oppgitt riktig header.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedTjenesten kunne ikke fastslå en betrodd klient-IP-adresse.

Hva du skal gjøre: Be butikkoperatøren kontrollere inngangsforbindelsen. Ikke sett inn videresendingsheadere selv.
Regler for nye forsøk: Prøv på nytt etter at den betrodde forbindelsesveien er gjenopprettet.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedKilde-IP-adressen er ikke på nøkkelens liste over tillatte adresser.

Hva du skal gjøre: Bruk en godkjent kildeadresse, eller be en autorisert administrator redigere nøkkelens IP-liste.
Regler for nye forsøk: Prøv først på nytt når adressen er tillatt.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedNøkkelen mangler en effektiv tilgang som kreves for denne operasjonen.

Hva du skal gjøre: Kontroller operasjonens nødvendige og betingede tilganger, nøkkelens tildelinger og utstederens tilgang.
Regler for nye forsøk: Prøv på nytt etter at en autorisert administrator har gitt nødvendig tilgang.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledAPI-tilgang er deaktivert for denne butikken.

Hva du skal gjøre: Be butikkeieren kontrollere det aktive abonnementet og API-tilgjengeligheten.
Regler for nye forsøk: Ikke prøv på nytt før API-tilgang er aktivert.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededEndringen ville overskride en grense i gjeldende abonnement.

Hva du skal gjøre: Kontroller den aktuelle ressursgrensen, og tilpass den planlagte endringen eller abonnementet.
Regler for nye forsøk: Prøv på nytt etter at grensen er avklart; bruk en ny idempotensnøkkel hvis forespørselen endres.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledGjeldende abonnement omfatter ikke denne operasjonen.

Hva du skal gjøre: Kontroller minimumsabonnementet som er oppgitt for operasjonen.
Regler for nye forsøk: Prøv på nytt når abonnementet tillater operasjonen og nøkkelen har nødvendige tilganger.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedEn abonnementsgrense blokkerer denne bestemte ressursen.

Hva du skal gjøre: Be eieren avklare ressursens abonnementsbegrensning.
Regler for nye forsøk: Ikke gjenta samme forespørsel så lenge ressursen er blokkert.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundRessursen mangler, er slettet eller er utilgjengelig under den oppgitte identifikatoren.

Hva du skal gjøre: Kontroller butikk, ressurssti og identifikator. Bruk identifikatorer returnert av denne butikken.
Regler for nye forsøk: Prøv først på nytt etter å ha rettet målet eller bekreftet at det finnes.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedEndepunktet støtter ikke denne HTTP-metoden.

Hva du skal gjøre: Bruk dokumentert metode; Allow-headeren viser metodene som støttes.
Regler for nye forsøk: Ikke gjenta metoden som ikke støttes.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedDenne idempotensnøkkelen tilhører en annen forespørsel.

Hva du skal gjøre: Finn den opprinnelige operasjonen. Bruk en ny nøkkel bare for en bevisst ny logisk operasjon.
Regler for nye forsøk: Ikke send endret innhold på nytt med nøkkelen som er i konflikt.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsEn unik verdi er i konflikt med en eksisterende ressurs.

Hva du skal gjøre: Les den eksisterende ressursen, og avgjør om du skal bruke den eller velge en annen unik verdi.
Regler for nye forsøk: Ikke gjenta den samme opprettelsen som gir konflikt.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useAndre ressurser er fortsatt avhengige av denne ressursen.

Hva du skal gjøre: Gå gjennom avhengighetene, og fjern eller endre dem gjennom støttede operasjoner før sletting.
Regler for nye forsøk: Prøv på nytt etter at avhengighetene er avklart.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictGjeldende forretningstilstand hindrer denne endringen.

Hva du skal gjøre: Les gjeldende tilstand, og velg en gyldig forretningsovergang.
Regler for nye forsøk: Ikke tving gjennom endringen automatisk eller send den gjentatte ganger.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictEn annen skriveoperasjon endret ressursen etter versjonen du leste.

Hva du skal gjøre: Les nyeste tilstand, avstem endringen, og send den nye expected_version.
Regler for nye forsøk: Bruk en ny idempotensnøkkel for den reviderte operasjonen; ikke overskriv blindt.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeForespørselen overskrider størrelsesgrensen.

Hva du skal gjøre: Reduser innholdet eller del arbeidet i støttede enkeltoperasjoner.
Regler for nye forsøk: Prøv på nytt med mindre, gyldige operasjoner med hver sin idempotensnøkkel.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeMedietypen eller innholdskodingen støttes ikke.

Hva du skal gjøre: Bruk Content-Type: application/json og støttet, ukomprimert innhold til JSON-skriveoperasjoner.
Regler for nye forsøk: Prøv på nytt etter å ha rettet medietypen eller kodingen.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedEtt eller flere felt eller parametere består ikke valideringen.

Hva du skal gjøre: Undersøk error.fields, og kontroller deretter obligatoriske felt, om null tillates, identifikatorer og tillatte verdier.
Regler for nye forsøk: Prøv på nytt med en rettet forespørsel; en endret skriveoperasjon er en ny logisk operasjon.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullDen korte API-køen er full; forespørselen har ikke begynt å kjøre.

Hva du skal gjøre: Sett forespørsler i kø, og følg svarheaderen Retry-After.
Regler for nye forsøk: Vent minst Retry-After sekunder, og legg til tilfeldig ventetid. Behold opprinnelig nøkkel og innhold når du prøver en skriveoperasjon på nytt.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutVentetiden i API-køen er utløpt; forespørselen har ikke begynt å kjøre.

Hva du skal gjøre: Sett forespørsler i kø, og følg svarheaderen Retry-After.
Regler for nye forsøk: Vent minst Retry-After sekunder, og legg til tilfeldig ventetid. Behold opprinnelig nøkkel og innhold når du prøver en skriveoperasjon på nytt.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededForespørselsfrekvensen overskrider gjeldende grense.

Hva du skal gjøre: Sett forespørsler i kø, og følg svarheaderen Retry-After.
Regler for nye forsøk: Vent minst Retry-After sekunder, og legg til tilfeldig ventetid. Behold opprinnelig nøkkel og innhold når du prøver en skriveoperasjon på nytt.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorDet oppsto en uventet tjenestefeil.

Hva du skal gjøre: Noter forespørselsidentifikatoren, og kontakt operatøren hvis feilen vedvarer; hold legitimasjonsopplysninger utenfor loggene.
Regler for nye forsøk: Bruk et begrenset antall forsøk med økende ventetid. Behold opprinnelig idempotensnøkkel og uendret innhold for en skriveoperasjon.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseGatewayen mottok ikke et gyldig API-svar.

Hva du skal gjøre: Ta vare på forespørselsidentifikatoren. Et feilsvar beviser ikke at en skriveoperasjon ikke ble utført.
Regler for nye forsøk: Bruk et begrenset antall forsøk med økende ventetid; gjenta samme logiske skriveoperasjon med opprinnelig Idempotency-Key og innhold.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI-et kan midlertidig ikke behandle forespørselen.

Hva du skal gjøre: Følg Retry-After når den er oppgitt, og ta vare på forespørselsidentifikatoren hvis avbruddet vedvarer.
Regler for nye forsøk: Bruk et begrenset antall forsøk med økende og tilfeldig ventetid; behold nøkkel og innhold ved gjentakelse av samme skriveoperasjon.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutGatewayens ventetid på API-et utløp.

Hva du skal gjøre: Ta vare på forespørselsidentifikatoren, og behandle skriveoperasjonens resultat som ukjent.
Regler for nye forsøk: Bruk et begrenset antall forsøk med økende ventetid; behold opprinnelig idempotensnøkkel og uendret innhold ved skriveoperasjoner.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}