Fel och återhämtning

Använd stabila felkoder för att avgöra om begäran ska korrigeras, vänta eller skickas igen.

Åtgärd

Styr programlogiken efter HTTP-status och error.code, inte den läsbara texten i error.message.
401 kräver giltig autentisering, 403 kräver ändrad åtkomst eller ändrat abonnemang och 409 kräver kontroll av den motstridiga operationen eller resursversionen.

Åtkomst nekad och nya försök

401: 401 betyder inte alltid att token har löpt ut. Om den har löpt ut, hämta en ny och upprepa läsningen högst en gång. Om tokenanropet ger 401, kontrollera nyckeln och stoppa automatiska försök.
403: Vid 403 ska du kontrollera behörigheter, IP-begränsningar och abonnemang. En ny token återställer inte återkallad åtkomst.

Autentisering

Regler för nya försök

Begränsa antalet nya försök vid tillfälliga fel och använd ökande väntetid med slumpmässig variation.
Följ Retry-After när det finns.
Om en skrivning når tidsgränsen kan resultatet vara okänt: behåll samma Idempotency-Key och oförändrad begäran när du försöker igen.
Katalogen nedan förklarar alla publicerade felkoder.

Säkra skrivningar

Anropsgränser

422 / 409

För priser ger ett ogiltigt valutaformat eller en ogiltig precision för beloppet 422 request.validation_failed.
En giltig valutakod som inte stämmer med den valda prislistan ger 409 resource.version_conflict.
Kontrollera kontexten och versionerna innan du försöker igen.

Felkatalog

400request.malformedBegäran kan inte tolkas.

Åtgärd: Kontrollera JSON-syntax, URL-kodning och begärans struktur.
Regler för nya försök: Försök igen efter att begäran korrigerats.

JSON

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

401authentication.invalid_credentialsAPI-nyckeln eller åtkomsttoken är ogiltig, utgången eller återkallad.

Åtgärd: Kontrollera butikens URL och autentiseringsuppgiften. Hämta en ny token med en aktiv API-nyckel.
Regler för nya försök: Försök igen efter att autentiseringen korrigerats. Undvik upprepade begäranden med ogiltiga uppgifter.

JSON

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

401authentication.requiredDet obligatoriska HTTP-huvudet Authorization saknas eller använder fel schema.

Åtgärd: Använd ApiKey när du begär en token och Bearer för resursoperationer.
Regler för nya försök: Försök igen med korrekt HTTP-huvud.

JSON

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

403authorization.client_ip_unverifiedTjänsten kunde inte fastställa en betrodd klient-IP-adress.

Åtgärd: Be butiksoperatören kontrollera ingressanslutningen. Lägg inte själv till vidarebefordringshuvuden.
Regler för nya försök: Försök igen när den betrodda anslutningsvägen har återställts.

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_allowedKällans IP-adress finns inte i nyckelns lista över tillåtna adresser.

Åtgärd: Använd en godkänd källadress eller be en behörig administratör redigera nyckelns IP-lista.
Regler för nya försök: Försök igen först när adressen är tillåten.

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_deniedNyckeln saknar en gällande behörighet som operationen kräver.

Åtgärd: Kontrollera operationens obligatoriska och villkorliga behörigheter, nyckelns behörigheter och utfärdarens åtkomst.
Regler för nya försök: Försök igen när en behörig administratör har gett nödvändig åtkomst.

JSON

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

403entitlements.api_disabledAPI-åtkomst är inaktiverad för butiken.

Åtgärd: Be butikens ägare kontrollera aktuellt abonnemang och API-tillgänglighet.
Regler för nya försök: Försök inte igen förrän API-åtkomst har aktiverats.

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 skulle överskrida en gräns i aktuellt abonnemang.

Åtgärd: Kontrollera tillämplig resursgräns och anpassa ändringen eller abonnemanget.
Regler för nya försök: Försök igen när begränsningen har lösts. Använd en ny idempotensnyckel om begäran ändras.

JSON

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

403entitlements.operation_disabledAktuellt abonnemang omfattar inte operationen.

Åtgärd: Kontrollera det lägsta abonnemang som anges för operationen.
Regler för nya försök: Försök igen när abonnemanget tillåter operationen och nyckeln har nödvändiga behörigheter.

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 abonnemangsgräns blockerar den här resursen.

Åtgärd: Be ägaren åtgärda resursens abonnemangsbegränsning.
Regler för nya försök: Upprepa inte samma begäran så länge resursen är blockerad.

JSON

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

404resource.not_foundResursen saknas, är borttagen eller är inte tillgänglig under angiven identifierare.

Åtgärd: Kontrollera butik, resurssökväg och identifierare. Använd identifierare som returnerats av den här butiken.
Regler för nya försök: Försök igen först när målet har korrigerats eller dess existens har bekräftats.

JSON

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

405request.method_not_allowedEndpointen stöder inte den här HTTP-metoden.

Åtgärd: Använd den dokumenterade metoden. HTTP-huvudet Allow anger vilka metoder som stöds.
Regler för nya försök: Försök inte igen med en metod som inte stöds.

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_reusedIdempotensnyckeln hör till en annan begäran.

Åtgärd: Hitta den ursprungliga operationen. Använd en ny nyckel endast för en avsiktligt ny logisk operation.
Regler för nya försök: Försök inte skicka ändrat innehåll med den motstridiga nyckeln.

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_existsEtt unikt värde krockar med en befintlig resurs.

Åtgärd: Läs den befintliga resursen och avgör om den ska användas eller om ett annat unikt värde ska väljas.
Regler för nya försök: Upprepa inte samma skapande som orsakar konflikten.

JSON

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

409resource.in_useAndra resurser är fortfarande beroende av resursen.

Åtgärd: Granska beroendena och ta bort eller ändra dem genom operationer som stöds innan du tar bort resursen.
Regler för nya försök: Försök igen när beroendena har lösts.

JSON

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

409resource.state_conflictAktuellt affärstillstånd förhindrar ändringen.

Åtgärd: Läs aktuellt tillstånd och välj en tillåten övergång.
Regler för nya försök: Tvinga inte automatiskt igenom ändringen och skicka inte samma motstridiga ändring upprepade gånger.

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 annan skrivning ändrade resursen efter den version du läste.

Åtgärd: Läs aktuella uppgifter, anpassa ändringen och skicka den nya expected_version.
Regler för nya försök: Använd en ny idempotensnyckel för den reviderade operationen. Skriv inte över utan kontroll.

JSON

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

413request.too_largeBegäran överskrider storleksgränsen.

Åtgärd: Minska innehållet eller dela upp arbetet i enskilda operationer som stöds.
Regler för nya försök: Skicka mindre, giltiga operationer med egna idempotensnycklar.

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 innehållskodningen stöds inte.

Åtgärd: För JSON-skrivningar använder du Content-Type: application/json och okomprimerat innehåll som stöds.
Regler för nya försök: Försök igen efter att medietyp eller kodning korrigerats.

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 flera fält eller parametrar klarar inte valideringen.

Åtgärd: Granska error.fields och kontrollera obligatoriska fält, tillåtna null-värden, identifierare och tillåtna värden.
Regler för nya försök: Skicka en korrigerad begäran. En ändrad skrivning är 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_fullAPI:ets korta kö är full; begäran har inte börjat köras.

Åtgärd: Lägg begäranden i kö och följ HTTP-huvudet Retry-After i svaret.
Regler för nya försök: Vänta minst Retry-After sekunder och lägg till slumpmässig fördröjning. Behåll ursprunglig nyckel och oförändrat innehåll vid nya skrivförsök.

JSON

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

429capacity.wait_timeoutVäntetiden i API-kön har gått ut; begäran har inte börjat köras.

Åtgärd: Lägg begäranden i kö och följ HTTP-huvudet Retry-After i svaret.
Regler för nya försök: Vänta minst Retry-After sekunder och lägg till slumpmässig fördröjning. Behåll ursprunglig nyckel och oförändrat innehåll vid nya skrivförsök.

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.exceededAnropsfrekvensen överskrider den tillämpliga gränsen.

Åtgärd: Lägg begäranden i kö och följ HTTP-huvudet Retry-After i svaret.
Regler för nya försök: Vänta minst Retry-After sekunder och lägg till slumpmässig fördröjning. Behåll ursprunglig nyckel och oförändrat innehåll vid nya skrivförsök.

JSON

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

500internal.errorEtt oväntat tjänstefel inträffade.

Åtgärd: Spara begärans identifierare och kontakta operatören om felet kvarstår. Lägg inte autentiseringsuppgifter i loggar.
Regler för nya försök: Använd begränsade nya försök med ökande väntetid. Behåll ursprunglig idempotensnyckel och oförändrat innehåll vid skrivningar.

JSON

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

502gateway.bad_responseGatewayen fick inget giltigt API-svar.

Åtgärd: Spara begärans identifierare. Ett misslyckat svar bevisar inte att skrivningen uteblev.
Regler för nya försök: Använd begränsade nya försök med ökande väntetid. Upprepa samma logiska skrivning med ursprunglig Idempotency-Key och oförändrat innehå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:et kan tillfälligt inte hantera begäran.

Åtgärd: Följ Retry-After när det finns och spara begärans identifierare om avbrottet kvarstår.
Regler för nya försök: Använd begränsade nya försök med ökande väntetid och slumpmässig variation. Behåll samma nyckel och innehåll när du upprepar samma skrivning.

JSON

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

504gateway.timeoutGatewayens tidsgräns överskreds medan den väntade på API:et.

Åtgärd: Spara begärans identifierare och betrakta skrivningens resultat som okänt.
Regler för nya försök: Använd begränsade nya försök med ökande väntetid. Behåll ursprunglig idempotensnyckel och oförändrat innehåll vid skrivningar.

JSON

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