Virheet ja palautuminen

Päätä vakaiden virhekoodien avulla, pitääkö korjata, odottaa vai yrittää uudelleen.

Toimintaohje

Ohjaa ohjelman toimintaa HTTP-tilakoodin ja error.code-kentän perusteella, älä ihmiselle luettavan error.message-kentän perusteella.
401 edellyttää kelvollista todentamista, 403 käyttöoikeuden tai paketin muutosta ja 409 ristiriitaisen toiminnon tai resurssiversion tarkistamista.

Pääsy estetty ja uudet yritykset

401: 401 ei aina tarkoita, että tunniste on vanhentunut. Jos se on vanhentunut, hae uusi ja toista lukupyyntö enintään kerran. Jos tunnisteen haku palauttaa 401:n, tarkista avain ja lopeta automaattiset yritykset.
403: Tarkista 403-virheen yhteydessä oikeudet, IP-rajoitukset ja tilaus. Uusi tunniste ei palauta peruttua käyttöoikeutta.

Todentaminen

Uudelleenyrityskäytäntö

Käytä tilapäisissä virheissä rajattua määrää uudelleenyrityksiä, kasvavaa odotusaikaa ja satunnaista lisäviivettä.
Noudata Retry-After-otsaketta, kun se annetaan.
Jos kirjoituspyyntö aikakatkaistaan, sen tulos voi olla tuntematon.
Säilytä sama Idempotency-Key ja muuttumaton pyyntö, kun yrität samaa loogista toimintoa uudelleen.
Alla oleva luettelo selittää kaikki julkaistut virhekoodit.

Turvalliset kirjoitukset

Pyyntörajat

422 / 409

Hinnoissa virheellinen valuutan muoto tai summan tarkkuus palauttaa virheen 422 request.validation_failed.
Kelvollinen valuuttakoodi, joka ei vastaa valittua hinnastoa, palauttaa virheen 409 resource.version_conflict.
Tarkista konteksti ja versiot ennen uutta yritystä.

Virheluettelo

400request.malformedPyyntöä ei voida jäsentää.

Toimintaohje: Tarkista JSON-syntaksi, URL-koodaus ja pyynnön rakenne.
Uudelleenyrityskäytäntö: Yritä uudelleen pyynnön korjaamisen jälkeen.

JSON

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

401authentication.invalid_credentialsAPI-avain tai käyttöoikeustunnus on virheellinen, vanhentunut tai peruutettu.

Toimintaohje: Tarkista kaupan URL-osoite ja tunnistetieto. Hanki uusi tunnus aktiivisella API-avaimella.
Uudelleenyrityskäytäntö: Yritä uudelleen todentamisen korjaamisen jälkeen. Vältä toistuvia pyyntöjä virheellisillä tunnuksilla.

JSON

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

401authentication.requiredVaadittu Authorization-otsake puuttuu tai sen menetelmä on väärä.

Toimintaohje: Käytä tunnusta pyydettäessä ApiKey-menetelmää ja resurssitoiminnoissa Bearer-menetelmää.
Uudelleenyrityskäytäntö: Yritä uudelleen oikean otsakkeen lisäämisen jälkeen.

JSON

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

403authorization.client_ip_unverifiedPalvelu ei pystynyt määrittämään luotettua asiakkaan IP-osoitetta.

Toimintaohje: Pyydä kaupan operaattoria tarkistamaan sisääntuloyhteys. Älä lisää välitysotsakkeita itse.
Uudelleenyrityskäytäntö: Yritä uudelleen luotetun yhteysreitin palautumisen jälkeen.

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_allowedLähde-IP-osoite ei ole avaimen sallittujen osoitteiden luettelossa.

Toimintaohje: Käytä hyväksyttyä lähdeosoitetta tai pyydä valtuutettua ylläpitäjää muokkaamaan avaimen IP-luetteloa.
Uudelleenyrityskäytäntö: Yritä uudelleen vasta, kun osoite on sallittu.

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_deniedAvaimella ei ole tämän toiminnon vaatimaa voimassa olevaa käyttöoikeutta.

Toimintaohje: Tarkista toiminnon vaaditut ja ehdolliset oikeudet, avaimen oikeudet ja sen myöntäjän käyttöoikeus.
Uudelleenyrityskäytäntö: Yritä uudelleen, kun valtuutettu ylläpitäjä on myöntänyt tarvittavan oikeuden.

JSON

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

403entitlements.api_disabledAPI:n käyttö on poistettu käytöstä tässä kaupassa.

Toimintaohje: Pyydä kaupan omistajaa tarkistamaan aktiivinen paketti ja API:n saatavuus.
Uudelleenyrityskäytäntö: Älä yritä uudelleen ennen kuin API:n käyttö on sallittu.

JSON

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

403entitlements.limit_exceededMuutos ylittäisi nykyisen paketin rajan.

Toimintaohje: Tarkista soveltuva resurssiraja ja muuta aiottua toimintoa tai pakettia.
Uudelleenyrityskäytäntö: Yritä uudelleen rajan ratkaisemisen jälkeen. Käytä uutta idempotenssiavainta, jos pyyntö muuttuu.

JSON

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

403entitlements.operation_disabledNykyinen paketti ei sisällä tätä toimintoa.

Toimintaohje: Tarkista toiminnolle ilmoitettu vähimmäispaketti.
Uudelleenyrityskäytäntö: Yritä uudelleen, kun paketti sallii toiminnon ja avaimella on tarvittavat oikeudet.

JSON

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

403entitlements.resource_blockedPaketin raja estää tämän tietyn resurssin käytön.

Toimintaohje: Pyydä omistajaa ratkaisemaan resurssin pakettirajoitus.
Uudelleenyrityskäytäntö: Älä toista samaa pyyntöä niin kauan kuin resurssi on estetty.

JSON

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

404resource.not_foundResurssi puuttuu, on poistettu tai ei ole saatavilla annetulla tunnisteella.

Toimintaohje: Tarkista kauppa, resurssipolku ja tunniste. Käytä tämän kaupan palauttamia tunnisteita.
Uudelleenyrityskäytäntö: Yritä uudelleen vasta kohteen korjaamisen tai sen olemassaolon varmistamisen jälkeen.

JSON

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

405request.method_not_allowedPäätepiste ei tue tätä HTTP-metodia.

Toimintaohje: Käytä dokumentoitua metodia. Allow-otsake ilmoittaa tuetut metodit.
Uudelleenyrityskäytäntö: Älä yritä tukematonta metodia uudelleen.

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_reusedTämä idempotenssiavain kuuluu eri pyynnölle.

Toimintaohje: Etsi alkuperäinen toiminto. Käytä uutta avainta vain tarkoituksella uudelle loogiselle toiminnolle.
Uudelleenyrityskäytäntö: Älä yritä muuttunutta sisältöä uudelleen ristiriitaisella avaimella.

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_existsYksilöllinen arvo on ristiriidassa olemassa olevan resurssin kanssa.

Toimintaohje: Lue olemassa oleva resurssi ja päätä, käytätkö sitä vai valitsetko toisen yksilöllisen arvon.
Uudelleenyrityskäytäntö: Älä toista samaa ristiriitaista luontia.

JSON

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

409resource.in_useMuut resurssit ovat edelleen riippuvaisia tästä resurssista.

Toimintaohje: Tarkista riippuvuudet ja poista tai muuta niitä tuettujen toimintojen kautta ennen poistoa.
Uudelleenyrityskäytäntö: Yritä uudelleen riippuvuuksien ratkaisemisen jälkeen.

JSON

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

409resource.state_conflictNykyinen liiketoimintatila estää tämän muutoksen.

Toimintaohje: Lue nykyinen tila ja valitse kelvollinen liiketoimintasiirtymä.
Uudelleenyrityskäytäntö: Älä pakota muutosta automaattisesti tai lähetä ristiriitaista muutosta toistuvasti.

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_conflictToinen kirjoitus muutti resurssia lukemasi version jälkeen.

Toimintaohje: Lue uusin tila, sovita muutoksesi siihen ja lähetä uusi expected_version.
Uudelleenyrityskäytäntö: Käytä tarkistettuun toimintoon uutta idempotenssiavainta. Älä ylikirjoita sokeasti.

JSON

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

413request.too_largePyyntö ylittää kokorajan.

Toimintaohje: Pienennä sisältöä tai jaa työ tuettuihin yksittäisiin toimintoihin.
Uudelleenyrityskäytäntö: Yritä pienempiä kelvollisia toimintoja omilla idempotenssiavaimillaan.

JSON

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

415request.unsupported_media_typeMediatyyppiä tai sisällön koodausta ei tueta.

Toimintaohje: Käytä JSON-kirjoituksissa Content-Type: application/json -otsaketta ja tuettua pakkaamatonta sisältöä.
Uudelleenyrityskäytäntö: Yritä uudelleen mediatyypin tai koodauksen korjaamisen jälkeen.

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_failedYksi tai useampi kenttä tai parametri ei läpäise validointia.

Toimintaohje: Tutki error.fields ja tarkista sitten pakolliset kentät, null-arvon salliminen, tunnisteet ja sallitut arvot.
Uudelleenyrityskäytäntö: Yritä korjattua pyyntöä uudelleen. Muuttunut kirjoitus on uusi looginen toiminto.

JSON

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

429capacity.queue_fullLyhyt API-jono on täynnä; pyynnön suorittamista ei ole aloitettu.

Toimintaohje: Aseta pyynnöt jonoon ja noudata vastauksen Retry-After-otsaketta.
Uudelleenyrityskäytäntö: Odota vähintään Retry-After sekuntia ja lisää satunnaista viivettä. Säilytä kirjoituksen uudelleenyrityksessä alkuperäinen avain ja sisältö.

JSON

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

429capacity.wait_timeoutOdotusaika API-jonossa päättyi; pyynnön suorittamista ei ole aloitettu.

Toimintaohje: Aseta pyynnöt jonoon ja noudata vastauksen Retry-After-otsaketta.
Uudelleenyrityskäytäntö: Odota vähintään Retry-After sekuntia ja lisää satunnaista viivettä. Säilytä kirjoituksen uudelleenyrityksessä alkuperäinen avain ja sisältö.

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.exceededPyyntötahti ylittää sovellettavan rajan.

Toimintaohje: Aseta pyynnöt jonoon ja noudata vastauksen Retry-After-otsaketta.
Uudelleenyrityskäytäntö: Odota vähintään Retry-After sekuntia ja lisää satunnaista viivettä. Säilytä kirjoituksen uudelleenyrityksessä alkuperäinen avain ja sisältö.

JSON

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

500internal.errorPalvelussa tapahtui odottamaton virhe.

Toimintaohje: Kirjaa pyynnön tunniste ja ota yhteys operaattoriin, jos virhe jatkuu. Älä sisällytä tunnistetietoja lokeihin.
Uudelleenyrityskäytäntö: Käytä rajattua määrää yrityksiä ja kasvavaa viivettä. Säilytä kirjoituksessa alkuperäinen idempotenssiavain ja muuttumaton sisältö.

JSON

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

502gateway.bad_responseYhdyskäytävä ei saanut kelvollista API-vastausta.

Toimintaohje: Säilytä pyynnön tunniste. Epäonnistunut vastaus ei todista, ettei kirjoitusta tehty.
Uudelleenyrityskäytäntö: Käytä rajattua määrää yrityksiä ja kasvavaa viivettä. Toista sama looginen kirjoitus alkuperäisellä Idempotency-Key-avaimella ja sisällöllä.

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 ei tilapäisesti pysty käsittelemään pyyntöä.

Toimintaohje: Noudata Retry-After-otsaketta, jos se annetaan, ja säilytä pyynnön tunniste, jos katkos jatkuu.
Uudelleenyrityskäytäntö: Käytä rajattua määrää yrityksiä, kasvavaa viivettä ja satunnaista lisäviivettä. Säilytä avain ja sisältö toistaessasi samaa kirjoitusta.

JSON

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

504gateway.timeoutYhdyskäytävä aikakatkaisi API:n odottamisen.

Toimintaohje: Säilytä pyynnön tunniste ja käsittele kirjoituksen tulosta tuntemattomana.
Uudelleenyrityskäytäntö: Käytä rajattua määrää yrityksiä ja kasvavaa viivettä. Käytä kirjoitukseen alkuperäistä idempotenssiavainta ja muuttumatonta sisältöä.

JSON

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