Kļūdas un atkopšana

Izmantojiet stabilus kļūdu kodus, lai izlemtu, vai labot, gaidīt vai mēģināt vēlreiz.

Ko darīt

Veidojiet loģiku pēc HTTP statusa un error.code, nevis cilvēkiem paredzētā error.message.
401 prasa derīgu autentifikāciju; 403 — piekļuves vai plāna izmaiņas; 409 — konfliktējošās darbības vai resursa versijas pārbaudi.

Piekļuve liegta un atkārtoti mēģinājumi

401: 401 ne vienmēr nozīmē, ka pilnvaras derīgums ir beidzies. Ja tas ir beidzies, saņemiet jaunu un atkārtojiet lasīšanu ne vairāk kā vienu reizi. Ja pilnvaras saņemšana atgriež 401, pārbaudiet atslēgu un apturiet automātiskos mēģinājumus.
403: Pie 403 pārbaudiet tiesības, IP ierobežojumus un plānu. Jauna pilnvara neatjauno atsauktu piekļuvi.

Autentifikācija

Atkārtošanas noteikumi

Īslaicīgām kļūmēm izmantojiet ierobežotu atkārtojumu skaitu ar augošu gaidīšanas laiku un nejaušu nobīdi.
Ievērojiet Retry-After, ja tas norādīts.
Ja rakstīšanai iestājas taimauts, rezultāts var būt nezināms: atkārtojot to pašu loģisko darbību, saglabājiet sākotnējo Idempotency-Key un nemainītu pieprasījumu.
Tālāk redzamais katalogs skaidro visus publicētos kļūdu kodus.

Droša rakstīšana

Pieprasījumu biežuma ierobežojumi

422 / 409

Cenām nederīgs valūtas formāts vai summas precizitāte rada 422 request.validation_failed.
Derīgs valūtas kods, kas neatbilst izvēlētajam cenrādim, rada 409 resource.version_conflict.
Pirms atkārtota mēģinājuma pārbaudiet kontekstu un versijas.

Kļūdu katalogs

400request.malformedPieprasījumu nevar parsēt.

Ko darīt: Pārbaudiet JSON sintaksi, URL kodējumu un pieprasījuma struktūru.
Atkārtošanas noteikumi: Atkārtojiet pēc pieprasījuma labošanas.

JSON

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

401authentication.invalid_credentialsAPI atslēga vai piekļuves marķieris ir nederīgs, beidzies vai atsaukts.

Ko darīt: Pārbaudiet veikala URL un piekļuves datus. Iegūstiet jaunu marķieri ar aktīvu API atslēgu.
Atkārtošanas noteikumi: Atkārtojiet pēc autentifikācijas labošanas; neveiciet atkārtotus pieprasījumus ar nederīgu marķieri.

JSON

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

401authentication.requiredTrūkst nepieciešamās Authorization galvenes vai tās shēma ir nepareiza.

Ko darīt: Marķiera pieprasījumam izmantojiet ApiKey, resursu darbībām — Bearer.
Atkārtošanas noteikumi: Atkārtojiet pēc pareizās galvenes pievienošanas.

JSON

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

403authorization.client_ip_unverifiedPakalpojums nevarēja noteikt uzticamu klienta IP adresi.

Ko darīt: Lūdziet veikala operatoram pārbaudīt ienākošā savienojuma ceļu. Nepievienojiet pārsūtīšanas galvenes paši.
Atkārtošanas noteikumi: Atkārtojiet pēc uzticamā savienojuma ceļa atjaunošanas.

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_allowedAvota IP adrese nav atslēgas atļauto adrešu sarakstā.

Ko darīt: Izmantojiet atļautu avota adresi vai lūdziet pilnvarotam administratoram rediģēt atslēgas IP sarakstu.
Atkārtošanas noteikumi: Atkārtojiet tikai pēc adreses atļaušanas.

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_deniedAtslēgai nav šai darbībai nepieciešamas spēkā esošas atļaujas.

Ko darīt: Pārbaudiet darbības obligātās un nosacītās atļaujas, atslēgas grantus un izdevēja piekļuvi.
Atkārtošanas noteikumi: Atkārtojiet pēc tam, kad pilnvarots administrators piešķir nepieciešamo piekļuvi.

JSON

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

403entitlements.api_disabledŠim veikalam API piekļuve ir atspējota.

Ko darīt: Lūdziet veikala īpašniekam pārbaudīt aktīvo plānu un API pieejamību.
Atkārtošanas noteikumi: Neatkārtojiet, līdz API piekļuve ir ieslēgta.

JSON

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

403entitlements.limit_exceededIzmaiņa pārsniegtu pašreizējā plāna limitu.

Ko darīt: Pārbaudiet attiecīgo resursa limitu un pielāgojiet iecerēto izmaiņu vai plānu.
Atkārtošanas noteikumi: Atkārtojiet pēc limita atrisināšanas; ja pieprasījums mainās, izmantojiet jaunu idempotences atslēgu.

JSON

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

403entitlements.operation_disabledPašreizējais plāns neietver šo darbību.

Ko darīt: Pārbaudiet darbībai norādīto minimālo plānu.
Atkārtošanas noteikumi: Atkārtojiet, kad plāns atļauj darbību un atslēgai ir nepieciešamās atļaujas.

JSON

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

403entitlements.resource_blockedPlāna limits bloķē šo konkrēto resursu.

Ko darīt: Lūdziet īpašniekam novērst resursa plāna ierobežojumu.
Atkārtošanas noteikumi: Neatkārtojiet to pašu pieprasījumu, kamēr resurss ir bloķēts.

JSON

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

404resource.not_foundResurss neeksistē, ir dzēsts vai nav pieejams ar norādīto identifikatoru.

Ko darīt: Pārbaudiet veikalu, resursa ceļu un identifikatoru. Izmantojiet šī veikala atgrieztos identifikatorus.
Atkārtošanas noteikumi: Atkārtojiet tikai pēc mērķa labošanas vai tā esamības apstiprināšanas.

JSON

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

405request.method_not_allowedGalapunkts neatbalsta šo HTTP metodi.

Ko darīt: Izmantojiet dokumentēto metodi; Allow galvene norāda atbalstītās metodes.
Atkārtošanas noteikumi: Neatkārtojiet neatbalstīto metodi.

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_reusedŠī idempotences atslēga pieder citam pieprasījumam.

Ko darīt: Atrodiet sākotnējo darbību. Jaunu atslēgu izmantojiet tikai apzināti jaunai loģiskai darbībai.
Atkārtošanas noteikumi: Neatkārtojiet mainītu saturu ar konfliktējošo atslēgu.

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_existsUnikāla vērtība konfliktē ar esošu resursu.

Ko darīt: Nolasiet esošo resursu un izlemiet, vai to izmantot vai izvēlēties citu unikālu vērtību.
Atkārtošanas noteikumi: Neatkārtojiet to pašu konfliktējošo izveidi.

JSON

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

409resource.in_useCiti resursi joprojām ir atkarīgi no šī resursa.

Ko darīt: Pārskatiet atkarības un pirms dzēšanas noņemiet vai mainiet tās ar atbalstītām darbībām.
Atkārtošanas noteikumi: Atkārtojiet pēc atkarību atrisināšanas.

JSON

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

409resource.state_conflictPašreizējais biznesa stāvoklis neļauj šo izmaiņu.

Ko darīt: Nolasiet pašreizējo stāvokli un izvēlieties derīgu biznesa pāreju.
Atkārtošanas noteikumi: Nespiediet automātiski un neatkārtojiet konfliktējošo izmaiņu.

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_conflictCita rakstīšana mainīja resursu pēc jūsu nolasītās versijas.

Ko darīt: Nolasiet jaunāko stāvokli, saskaņojiet izmaiņu un iesniedziet jaunu expected_version.
Atkārtošanas noteikumi: Pārskatītajai darbībai izmantojiet jaunu idempotences atslēgu; nepārrakstiet akli.

JSON

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

413request.too_largePieprasījums pārsniedz izmēra limitu.

Ko darīt: Samaziniet saturu vai sadaliet darbu atbalstītās atsevišķās darbībās.
Atkārtošanas noteikumi: Atkārtojiet mazākas derīgas darbības ar katras savu idempotences atslēgu.

JSON

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

415request.unsupported_media_typeMultivides tips vai satura kodējums nav atbalstīts.

Ko darīt: JSON rakstīšanai izmantojiet Content-Type: application/json un atbalstītu nesaspiestu saturu.
Atkārtošanas noteikumi: Atkārtojiet pēc multivides tipa vai kodējuma labošanas.

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_failedViens vai vairāki lauki vai parametri neiztur validāciju.

Ko darīt: Apskatiet error.fields, pēc tam pārbaudiet obligātos laukus, null atļaušanu, identifikatorus un atļautās vērtības.
Atkārtošanas noteikumi: Atkārtojiet labotu pieprasījumu; mainīta rakstīšana ir jauna loģiska darbība.

JSON

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

429capacity.queue_fullĪsā API rinda ir pilna; pieprasījuma izpilde nav sākusies.

Ko darīt: Ievietojiet pieprasījumus rindā un ievērojiet atbildes Retry-After galveni.
Atkārtošanas noteikumi: Gaidiet vismaz Retry-After sekundes un pievienojiet nejaušu aizkavi. Atkārtojot rakstīšanu, saglabājiet sākotnējo atslēgu un saturu.

JSON

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

429capacity.wait_timeoutBeidzies gaidīšanas laiks API rindā; pieprasījuma izpilde nav sākusies.

Ko darīt: Ievietojiet pieprasījumus rindā un ievērojiet atbildes Retry-After galveni.
Atkārtošanas noteikumi: Gaidiet vismaz Retry-After sekundes un pievienojiet nejaušu aizkavi. Atkārtojot rakstīšanu, saglabājiet sākotnējo atslēgu un saturu.

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.exceededPieprasījumu biežums pārsniedz piemērojamo limitu.

Ko darīt: Ievietojiet pieprasījumus rindā un ievērojiet atbildes Retry-After galveni.
Atkārtošanas noteikumi: Gaidiet vismaz Retry-After sekundes un pievienojiet nejaušu aizkavi. Atkārtojot rakstīšanu, saglabājiet sākotnējo atslēgu un saturu.

JSON

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

500internal.errorRadās neparedzēta pakalpojuma kļūda.

Ko darīt: Pierakstiet pieprasījuma identifikatoru un, ja kļūda turpinās, sazinieties ar operatoru; neiekļaujiet piekļuves datus žurnālos.
Atkārtošanas noteikumi: Izmantojiet ierobežotus atkārtojumus ar pieaugošu aizkavi. Rakstīšanai saglabājiet sākotnējo idempotences atslēgu un nemainītu saturu.

JSON

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

502gateway.bad_responseVārteja nesaņēma derīgu API atbildi.

Ko darīt: Saglabājiet pieprasījuma identifikatoru. Neveiksmīga atbilde nepierāda, ka rakstīšana nav veikta.
Atkārtošanas noteikumi: Izmantojiet ierobežotus atkārtojumus ar pieaugošu aizkavi; to pašu loģisko rakstīšanu atkārtojiet ar sākotnējo Idempotency-Key un saturu.

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 īslaicīgi nevar apstrādāt pieprasījumu.

Ko darīt: Ievērojiet Retry-After, ja norādīts, un saglabājiet pieprasījuma identifikatoru, ja pārtraukums turpinās.
Atkārtošanas noteikumi: Izmantojiet ierobežotus atkārtojumus ar augošu un nejaušu aizkavi; atkārtojot to pašu rakstīšanu, saglabājiet atslēgu un saturu.

JSON

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

504gateway.timeoutVārtejai beidzās API atbildes gaidīšanas laiks.

Ko darīt: Saglabājiet pieprasījuma identifikatoru un uzskatiet rakstīšanas rezultātu par nezināmu.
Atkārtošanas noteikumi: Izmantojiet ierobežotus atkārtojumus ar pieaugošu aizkavi; rakstīšanai saglabājiet sākotnējo idempotences atslēgu un nemainītu saturu.

JSON

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