Fouten en herstel

Gebruik stabiele foutcodes om te bepalen of u moet corrigeren, wachten of opnieuw proberen.

Wat te doen

Baseer beslissingen op de HTTP-status en error.code, niet op de leesbare error.message.
Een 401 vereist geldige authenticatie; 403 vereist aangepaste toegang of een geschikt abonnement; 409 vereist controle van de conflicterende bewerking of resourceversie.

Toegang geweigerd en opnieuw proberen

401: 401 betekent niet altijd dat het token verlopen is. Is het verlopen, haal dan een nieuw token op en herhaal het leesverzoek hoogstens één keer. Geeft het ophalen van een token 401, controleer dan de sleutel en stop automatische pogingen.
403: Controleer bij 403 de rechten, IP-beperkingen en het abonnement. Een nieuw token herstelt ingetrokken toegang niet.

Authenticatie

Beleid voor opnieuw proberen

Beperk herhaalde pogingen en gebruik toenemende wachttijden met willekeurige spreiding.
Volg Retry-After wanneer deze header aanwezig is.
Bij een time-out van een schrijfbewerking kan het resultaat onbekend zijn: behoud dezelfde Idempotency-Key en hetzelfde verzoek wanneer u die logische bewerking herhaalt.
De onderstaande catalogus licht elke gepubliceerde foutcode toe.

Veilig schrijven

Verzoeklimieten

422 / 409

Bij prijzen geeft een ongeldige valuta-indeling of precisie van het bedrag 422 request.validation_failed.
Een geldige valutacode die afwijkt van de geselecteerde prijslijst geeft 409 resource.version_conflict.
Controleer de context en versies voordat je het opnieuw probeert.

Foutencatalogus

400request.malformedHet verzoek kan niet worden ontleed.

Wat te doen: Controleer de JSON-syntaxis, URL-codering en verzoekstructuur.
Beleid voor opnieuw proberen: Probeer het opnieuw nadat het verzoek is gecorrigeerd.

JSON

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

401authentication.invalid_credentialsDe API-sleutel of het toegangstoken is ongeldig, verlopen of ingetrokken.

Wat te doen: Controleer de winkel-URL en het toegangsbewijs. Vraag een nieuw token aan met een actieve API-sleutel.
Beleid voor opnieuw proberen: Probeer het opnieuw nadat de authenticatie is hersteld; blijf geen ongeldige tokenverzoeken sturen.

JSON

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

401authentication.requiredDe vereiste Authorization-header ontbreekt of het authenticatieschema is onjuist.

Wat te doen: Gebruik ApiKey bij het aanvragen van een token en Bearer voor resourcebewerkingen.
Beleid voor opnieuw proberen: Probeer het opnieuw met de juiste header.

JSON

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

403authorization.client_ip_unverifiedDe dienst kon geen vertrouwd IP-adres van de client vaststellen.

Wat te doen: Vraag de winkeloperator de ingress-route te controleren. Voeg zelf geen forwardingheaders toe.
Beleid voor opnieuw proberen: Probeer het opnieuw nadat het vertrouwde verbindingspad is hersteld.

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_allowedHet bron-IP-adres staat niet op de lijst met toegestane adressen voor deze sleutel.

Wat te doen: Gebruik een goedgekeurd bronadres of vraag een bevoegde beheerder de IP-lijst van de sleutel te wijzigen.
Beleid voor opnieuw proberen: Probeer het pas opnieuw nadat het adres is toegestaan.

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_deniedDe sleutel heeft geen effectief recht dat voor deze bewerking vereist is.

Wat te doen: Controleer de verplichte en voorwaardelijke rechten van de bewerking, de sleutelrechten en de toegang van de uitgever.
Beleid voor opnieuw proberen: Probeer het opnieuw nadat een bevoegde beheerder de vereiste toegang heeft verleend.

JSON

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

403entitlements.api_disabledAPI-toegang is uitgeschakeld voor deze winkel.

Wat te doen: Vraag de winkeleigenaar het actieve abonnement en de beschikbaarheid van de API te controleren.
Beleid voor opnieuw proberen: Probeer het pas opnieuw nadat API-toegang is ingeschakeld.

JSON

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

403entitlements.limit_exceededDe wijziging zou een limiet van het huidige abonnement overschrijden.

Wat te doen: Controleer de toepasselijke resourcelimiet en pas de bedoelde wijziging of het abonnement aan.
Beleid voor opnieuw proberen: Probeer het opnieuw nadat de limiet is opgelost; gebruik een nieuwe idempotentiesleutel als het verzoek verandert.

JSON

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

403entitlements.operation_disabledHet huidige abonnement omvat deze bewerking niet.

Wat te doen: Controleer het minimale abonnement dat bij de bewerking staat.
Beleid voor opnieuw proberen: Probeer het opnieuw zodra het abonnement de bewerking toestaat en de sleutel de vereiste rechten heeft.

JSON

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

403entitlements.resource_blockedEen abonnementsgrens blokkeert deze specifieke resource.

Wat te doen: Vraag de eigenaar de abonnementsbeperking van deze resource op te lossen.
Beleid voor opnieuw proberen: Herhaal hetzelfde verzoek niet zolang de resource geblokkeerd blijft.

JSON

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

404resource.not_foundDe resource ontbreekt, is verwijderd of is niet beschikbaar onder de opgegeven identificatie.

Wat te doen: Controleer de winkel, het resourcepad en de identificatie. Gebruik identificaties die deze winkel heeft teruggegeven.
Beleid voor opnieuw proberen: Probeer het alleen opnieuw nadat het doel is gecorrigeerd of het bestaan ervan is bevestigd.

JSON

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

405request.method_not_allowedHet endpoint ondersteunt deze HTTP-methode niet.

Wat te doen: Gebruik de gedocumenteerde methode; de Allow-header vermeldt de ondersteunde methoden.
Beleid voor opnieuw proberen: Herhaal de niet-ondersteunde methode niet.

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_reusedDeze idempotentiesleutel hoort bij een ander verzoek.

Wat te doen: Zoek de oorspronkelijke bewerking. Gebruik alleen een nieuwe sleutel voor een bewust nieuwe logische bewerking.
Beleid voor opnieuw proberen: Probeer gewijzigde inhoud niet opnieuw met de conflicterende sleutel.

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_existsEen unieke waarde conflicteert met een bestaande resource.

Wat te doen: Lees de bestaande resource en bepaal of u die gebruikt of een andere unieke waarde kiest.
Beleid voor opnieuw proberen: Herhaal dezelfde conflicterende aanmaakbewerking niet.

JSON

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

409resource.in_useAndere resources zijn nog afhankelijk van deze resource.

Wat te doen: Controleer de afhankelijkheden en verwijder of wijzig deze via ondersteunde bewerkingen voordat u de resource verwijdert.
Beleid voor opnieuw proberen: Probeer het opnieuw nadat de afhankelijkheden zijn opgelost.

JSON

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

409resource.state_conflictDe huidige zakelijke status verhindert deze wijziging.

Wat te doen: Lees de huidige status en kies een geldige statusovergang.
Beleid voor opnieuw proberen: Forceer of herhaal de conflicterende wijziging niet automatisch.

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_conflictEen andere schrijfbewerking heeft de resource gewijzigd na de door u gelezen versie.

Wat te doen: Lees de nieuwste status, stem uw wijziging daarop af en stuur de nieuwe expected_version.
Beleid voor opnieuw proberen: Gebruik een nieuwe idempotentiesleutel voor de herziene bewerking; overschrijf gegevens niet blindelings.

JSON

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

413request.too_largeHet verzoek overschrijdt de groottelimiet.

Wat te doen: Verklein de inhoud of verdeel het werk over ondersteunde afzonderlijke bewerkingen.
Beleid voor opnieuw proberen: Probeer kleinere, geldige bewerkingen met elk een eigen idempotentiesleutel.

JSON

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

415request.unsupported_media_typeHet mediatype of de inhoudscodering wordt niet ondersteund.

Wat te doen: Gebruik bij JSON-schrijfbewerkingen Content-Type: application/json en ondersteunde, ongecomprimeerde inhoud.
Beleid voor opnieuw proberen: Probeer het opnieuw nadat het mediatype of de codering is gecorrigeerd.

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_failedEen of meer velden of parameters voldoen niet aan de validatie.

Wat te doen: Bekijk error.fields en controleer verplichte velden, null-toestemming, identificaties en toegestane waarden.
Beleid voor opnieuw proberen: Probeer een gecorrigeerd verzoek; een gewijzigde schrijfbewerking is een nieuwe logische bewerking.

JSON

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

429capacity.queue_fullDe korte API-wachtrij is vol; de uitvoering van het verzoek is niet begonnen.

Wat te doen: Plaats verzoeken in een wachtrij en volg de Retry-After-header van het antwoord.
Beleid voor opnieuw proberen: Wacht minimaal Retry-After seconden en voeg willekeurige spreiding toe. Behoud de oorspronkelijke sleutel en inhoud wanneer u een schrijfbewerking herhaalt.

JSON

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

429capacity.wait_timeoutDe wachttijd in de API-wachtrij is verstreken; de uitvoering van het verzoek is niet begonnen.

Wat te doen: Plaats verzoeken in een wachtrij en volg de Retry-After-header van het antwoord.
Beleid voor opnieuw proberen: Wacht minimaal Retry-After seconden en voeg willekeurige spreiding toe. Behoud de oorspronkelijke sleutel en inhoud wanneer u een schrijfbewerking herhaalt.

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.exceededDe verzoekfrequentie overschrijdt de toepasselijke limiet.

Wat te doen: Plaats verzoeken in een wachtrij en volg de Retry-After-header van het antwoord.
Beleid voor opnieuw proberen: Wacht minimaal Retry-After seconden en voeg willekeurige spreiding toe. Behoud de oorspronkelijke sleutel en inhoud wanneer u een schrijfbewerking herhaalt.

JSON

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

500internal.errorEr is een onverwachte fout in de dienst opgetreden.

Wat te doen: Noteer de verzoekidentificatie en neem bij een aanhoudende fout contact op met de operator; houd toegangsbewijzen buiten logbestanden.
Beleid voor opnieuw proberen: Gebruik begrensde herhaalde pogingen met toenemende wachttijd. Behoud bij een schrijfbewerking de oorspronkelijke idempotentiesleutel en ongewijzigde inhoud.

JSON

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

502gateway.bad_responseDe gateway ontving geen geldig API-antwoord.

Wat te doen: Bewaar de verzoekidentificatie. Een mislukt antwoord bewijst niet dat een schrijfbewerking niet is uitgevoerd.
Beleid voor opnieuw proberen: Gebruik begrensde herhaalde pogingen met toenemende wachttijd; herhaal dezelfde logische schrijfbewerking met de oorspronkelijke Idempotency-Key en inhoud.

JSON

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

503service.unavailableDe API kan het verzoek tijdelijk niet verwerken.

Wat te doen: Volg Retry-After wanneer die header aanwezig is en bewaar de verzoekidentificatie als de storing aanhoudt.
Beleid voor opnieuw proberen: Gebruik begrensde herhaalde pogingen met toenemende wachttijd en willekeurige spreiding; behoud sleutel en inhoud bij het herhalen van dezelfde schrijfbewerking.

JSON

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

504gateway.timeoutDe gateway overschreed de wachttijd voor het API-antwoord.

Wat te doen: Bewaar de verzoekidentificatie en behandel het resultaat van een schrijfbewerking als onbekend.
Beleid voor opnieuw proberen: Gebruik begrensde herhaalde pogingen met toenemende wachttijd; behoud voor een schrijfbewerking de oorspronkelijke idempotentiesleutel en ongewijzigde inhoud.

JSON

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