Fejl og genopretning

Brug stabile fejlkoder til at afgøre, om du skal rette, vente eller prøve igen.

Hvad du skal gøre

Lad programmet reagere på HTTP-status og error.code, ikke den menneskeligt læsbare error.message.
En 401 kræver gyldig godkendelse; 403 kræver ændringer af adgang eller abonnement; 409 kræver kontrol af den modstridende operation eller ressourceversion.

Adgang nægtet og nye forsøg

401: 401 betyder ikke altid, at tokenet er udløbet. Hvis det er udløbet, skal du hente et nyt og gentage læsningen højst én gang. Hvis hentning af tokenet giver 401, skal du kontrollere nøglen og stoppe automatiske forsøg.
403: Ved 403 skal du kontrollere rettigheder, IP-begrænsninger og abonnement. Et nyt token gendanner ikke tilbagekaldt adgang.

Godkendelse

Regler for genforsøg

Brug et begrænset antal genforsøg med stigende og tilfældig ventetid ved midlertidige fejl.
Respektér Retry-After, når headeren findes.
Hvis en skriveoperation får timeout, kan resultatet være ukendt: behold samme Idempotency-Key og uændret forespørgsel, når du gentager den logiske operation.
Kataloget nedenfor forklarer alle offentliggjorte fejlkoder.

Sikre skriveoperationer

Forespørgselsgrænser

422 / 409

For priser giver et ugyldigt valutaformat eller en ugyldig præcision for beløbet 422 request.validation_failed.
En gyldig valutakode, der ikke stemmer overens med den valgte prisliste, giver 409 resource.version_conflict.
Kontrollér konteksten og versionerne, før du prøver igen.

Fejlkatalog

400request.malformedForespørgslen kan ikke fortolkes.

Hvad du skal gøre: Kontrollér JSON-syntaks, URL-kodning og forespørgslens struktur.
Regler for genforsøg: Prøv igen efter at have rettet forespørgslen.

JSON

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

401authentication.invalid_credentialsAPI-nøglen eller adgangstokenet er ugyldigt, udløbet eller tilbagekaldt.

Hvad du skal gøre: Kontrollér butikkens URL og legitimationsoplysningen. Hent et nyt token med en aktiv API-nøgle.
Regler for genforsøg: Prøv igen efter at have rettet godkendelsen; undgå gentagne forespørgsler 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-header mangler, eller dens metode er forkert.

Hvad du skal gøre: Brug ApiKey, når du anmoder om et token, og Bearer til ressourceoperationer.
Regler for genforsøg: Prøv igen efter at have tilføjet den korrekte 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 betroet klient-IP-adresse.

Hvad du skal gøre: Bed butiksoperatøren kontrollere indgangsforbindelsen. Indsæt ikke selv videresendelsesheadere.
Regler for genforsøg: Prøv igen, når den betroede forbindelsesvej er genoprettet.

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 findes ikke på nøglens liste over tilladte adresser.

Hvad du skal gøre: Brug en godkendt kildeadresse, eller bed en autoriseret administrator redigere nøglens IP-liste.
Regler for genforsøg: Prøv først igen, når adressen er tilladt.

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øglen har ikke en effektiv rettighed, der kræves til denne operation.

Hvad du skal gøre: Kontrollér operationens nødvendige og betingede rettigheder, nøglens tildelinger og udstederens adgang.
Regler for genforsøg: Prøv igen, når en autoriseret administrator har givet den nødvendige adgang.

JSON

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

403entitlements.api_disabledAPI-adgang er deaktiveret for denne butik.

Hvad du skal gøre: Bed butiksejeren kontrollere det aktive abonnement og API-tilgængeligheden.
Regler for genforsøg: Prøv ikke igen, før API-adgang er aktiveret.

JSON

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

403entitlements.limit_exceededÆndringen ville overskride en grænse i det aktuelle abonnement.

Hvad du skal gøre: Kontrollér den gældende ressourcegrænse, og tilpas ændringen eller abonnementet.
Regler for genforsøg: Prøv igen, når grænsen er afklaret; brug en ny idempotensnøgle, hvis forespørgslen ændres.

JSON

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

403entitlements.operation_disabledDet aktuelle abonnement omfatter ikke denne operation.

Hvad du skal gøre: Kontrollér det minimumsabonnement, der er angivet for operationen.
Regler for genforsøg: Prøv igen, når abonnementet tillader operationen, og nøglen har de nødvendige rettigheder.

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 abonnementsgrænse blokerer denne bestemte ressource.

Hvad du skal gøre: Bed ejeren afklare ressourcens abonnementsbegrænsning.
Regler for genforsøg: Gentag ikke samme forespørgsel, mens ressourcen stadig er blokeret.

JSON

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

404resource.not_foundRessourcen mangler, er slettet eller er ikke tilgængelig under den angivne identifikator.

Hvad du skal gøre: Kontrollér butik, ressourcesti og identifikator. Brug identifikatorer returneret af denne butik.
Regler for genforsøg: Prøv først igen efter at have rettet målet eller bekræftet, at det findes.

JSON

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

405request.method_not_allowedEndepunktet understøtter ikke denne HTTP-metode.

Hvad du skal gøre: Brug den dokumenterede metode; Allow-headeren angiver de understøttede metoder.
Regler for genforsøg: Gentag ikke den ikke-understøttede metode.

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øgle tilhører en anden forespørgsel.

Hvad du skal gøre: Find den oprindelige operation. Brug kun en ny nøgle til en bevidst ny logisk operation.
Regler for genforsøg: Gentag ikke ændret indhold med den modstridende nøgle.

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 værdi er i konflikt med en eksisterende ressource.

Hvad du skal gøre: Læs den eksisterende ressource, og afgør, om du skal bruge den eller vælge en anden unik værdi.
Regler for genforsøg: Gentag ikke den samme modstridende oprettelse.

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 ressourcer afhænger stadig af denne ressource.

Hvad du skal gøre: Gennemgå afhængighederne, og fjern eller ændr dem gennem understøttede operationer før sletning.
Regler for genforsøg: Prøv igen, når afhængighederne er afklaret.

JSON

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

409resource.state_conflictDen aktuelle forretningstilstand forhindrer denne ændring.

Hvad du skal gøre: Læs den aktuelle tilstand, og vælg en gyldig forretningsovergang.
Regler for genforsøg: Gennemtving ikke automatisk ændringen, og indsend den ikke gentagne gange.

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 anden skriveoperation ændrede ressourcen efter den version, du læste.

Hvad du skal gøre: Læs den nyeste tilstand, afstem ændringen, og send den nye expected_version.
Regler for genforsøg: Brug en ny idempotensnøgle til den reviderede operation; overskriv ikke blindt.

JSON

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

413request.too_largeForespørgslen overskrider størrelsesgrænsen.

Hvad du skal gøre: Reducér indholdet, eller opdel arbejdet i understøttede enkeltoperationer.
Regler for genforsøg: Prøv igen med mindre, gyldige operationer med hver deres idempotensnøgle.

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 indholdskodningen understøttes ikke.

Hvad du skal gøre: Brug Content-Type: application/json og understøttet ukomprimeret indhold til JSON-skriveoperationer.
Regler for genforsøg: Prøv igen efter at have rettet medietypen eller kodningen.

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_failedEt eller flere felter eller parametre består ikke valideringen.

Hvad du skal gøre: Undersøg error.fields, og kontrollér derefter obligatoriske felter, mulighed for null, identifikatorer og tilladte værdier.
Regler for genforsøg: Prøv igen med en rettet forespørgsel; en ændret skriveoperation er en ny logisk operation.

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ø er fuld; anmodningen er ikke begyndt at blive udført.

Hvad du skal gøre: Sæt forespørgsler i kø, og respektér svarheaderen Retry-After.
Regler for genforsøg: Vent mindst Retry-After sekunder, og tilføj tilfældig ventetid. Bevar oprindelig nøgle og indhold ved genforsøg på en skriveoperation.

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 udløbet; anmodningen er ikke begyndt at blive udført.

Hvad du skal gøre: Sæt forespørgsler i kø, og respektér svarheaderen Retry-After.
Regler for genforsøg: Vent mindst Retry-After sekunder, og tilføj tilfældig ventetid. Bevar oprindelig nøgle og indhold ved genforsøg på en skriveoperation.

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ørgselsfrekvensen overskrider den gældende grænse.

Hvad du skal gøre: Sæt forespørgsler i kø, og respektér svarheaderen Retry-After.
Regler for genforsøg: Vent mindst Retry-After sekunder, og tilføj tilfældig ventetid. Bevar oprindelig nøgle og indhold ved genforsøg på en skriveoperation.

JSON

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

500internal.errorDer opstod en uventet tjenestefejl.

Hvad du skal gøre: Notér forespørgsels-id'et, og kontakt operatøren, hvis fejlen fortsætter; udelad legitimationsoplysninger fra logfiler.
Regler for genforsøg: Brug et begrænset antal genforsøg med stigende ventetid. Behold den oprindelige idempotensnøgle og uændret indhold ved en skriveoperation.

JSON

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

502gateway.bad_responseGatewayen modtog ikke et gyldigt API-svar.

Hvad du skal gøre: Gem forespørgsels-id'et. Et fejlsvar beviser ikke, at en skriveoperation ikke blev udført.
Regler for genforsøg: Brug et begrænset antal genforsøg med stigende ventetid; gentag samme logiske skriveoperation med dens oprindelige Idempotency-Key og indhold.

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 midlertidigt ikke behandle forespørgslen.

Hvad du skal gøre: Respektér Retry-After, når headeren findes, og gem forespørgsels-id'et, hvis afbrydelsen fortsætter.
Regler for genforsøg: Brug et begrænset antal genforsøg med stigende og tilfældig ventetid; bevar nøgle og indhold ved gentagelse af samme skriveoperation.

JSON

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

504gateway.timeoutGatewayens ventetid på API'et udløb.

Hvad du skal gøre: Gem forespørgsels-id'et, og betragt skriveoperationens resultat som ukendt.
Regler for genforsøg: Brug et begrænset antal genforsøg med stigende ventetid; genbrug den oprindelige idempotensnøgle og uændret indhold ved skriveoperationer.

JSON

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