Erori și recuperare

Folosiți codurile stabile de eroare pentru a decide dacă trebuie să corectați, să așteptați sau să reîncercați.

Ce trebuie făcut

Bazați logica pe starea HTTP și pe error.code, nu pe textul error.message destinat utilizatorilor.
Un răspuns 401 necesită autentificare validă; 403 necesită modificarea accesului sau a planului; 409 necesită verificarea operației aflate în conflict sau a versiunii resursei.

Acces refuzat și reîncercări

401: 401 nu înseamnă întotdeauna că tokenul a expirat. Dacă a expirat, obține unul nou și repetă citirea cel mult o dată. Dacă obținerea tokenului returnează 401, verifică cheia și oprește încercările automate.
403: La 403, verifică permisiunile, restricțiile IP și planul. Un token nou nu restabilește accesul revocat.

Autentificare

Reguli de reîncercare

Pentru erori temporare, folosiți un număr limitat de reîncercări, cu întârzieri progresive și variație aleatorie.
Respectați Retry-After când este prezent.
Dacă o scriere depășește timpul de așteptare, rezultatul poate fi necunoscut: păstrați aceeași valoare Idempotency-Key și cererea neschimbată la reîncercarea acelei operații logice.
Catalogul de mai jos explică fiecare cod de eroare publicat.

Scrieri sigure

Limite de cereri

422 / 409

Pentru prețuri, un format de monedă sau o precizie a sumei nevalide returnează 422 request.validation_failed.
Un cod de monedă valid, dar diferit de cel al listei de prețuri selectate, returnează 409 resource.version_conflict.
Verifică contextul și versiunile înainte de a reîncerca.

Catalog de erori

400request.malformedCererea nu poate fi interpretată.

Ce trebuie făcut: Verificați sintaxa JSON, codificarea URL-ului și structura cererii.
Reguli de reîncercare: Reîncercați după corectarea cererii.

JSON

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

401authentication.invalid_credentialsCheia API sau tokenul de acces este invalid, a expirat ori a fost revocat.

Ce trebuie făcut: Verificați URL-ul magazinului și credențialul. Obțineți un token nou folosind o cheie API activă.
Reguli de reîncercare: Reîncercați după corectarea autentificării; evitați cererile repetate cu tokenuri invalide.

JSON

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

401authentication.requiredAntetul Authorization necesar lipsește sau folosește o schemă incorectă.

Ce trebuie făcut: Folosiți ApiKey la solicitarea unui token și Bearer pentru operațiile asupra resurselor.
Reguli de reîncercare: Reîncercați după furnizarea antetului corect.

JSON

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

403authorization.client_ip_unverifiedServiciul nu a putut stabili o adresă IP de client de încredere.

Ce trebuie făcut: Cereți operatorului magazinului să verifice traseul de acces. Nu introduceți singuri antete de redirecționare.
Reguli de reîncercare: Reîncercați după restabilirea traseului de conexiune de încredere.

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_allowedAdresa IP sursă nu se află în lista adreselor permise pentru cheie.

Ce trebuie făcut: Folosiți o adresă sursă aprobată sau cereți unui administrator autorizat să editeze lista IP a cheii.
Reguli de reîncercare: Reîncercați numai după ce adresa este permisă.

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_deniedCheia nu are o permisiune efectivă necesară acestei operații.

Ce trebuie făcut: Verificați permisiunile obligatorii și condiționale ale operației, permisiunile cheii și accesul emitentului.
Reguli de reîncercare: Reîncercați după ce un administrator autorizat acordă accesul necesar.

JSON

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

403entitlements.api_disabledAccesul API este dezactivat pentru acest magazin.

Ce trebuie făcut: Cereți proprietarului magazinului să verifice planul activ și disponibilitatea API.
Reguli de reîncercare: Nu reîncercați până la activarea accesului API.

JSON

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

403entitlements.limit_exceededModificarea ar depăși o limită a planului curent.

Ce trebuie făcut: Verificați limita aplicabilă resursei și adaptați modificarea dorită sau planul.
Reguli de reîncercare: Reîncercați după rezolvarea limitei; folosiți o cheie de idempotență nouă dacă cererea se schimbă.

JSON

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

403entitlements.operation_disabledPlanul curent nu include această operație.

Ce trebuie făcut: Verificați planul minim indicat pentru operație.
Reguli de reîncercare: Reîncercați după ce planul permite operația și cheia are permisiunile necesare.

JSON

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

403entitlements.resource_blockedO limită a planului blochează această resursă.

Ce trebuie făcut: Cereți proprietarului să rezolve restricția impusă resursei de plan.
Reguli de reîncercare: Nu repetați aceeași cerere cât timp resursa rămâne blocată.

JSON

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

404resource.not_foundResursa lipsește, a fost ștearsă sau nu este disponibilă sub identificatorul furnizat.

Ce trebuie făcut: Verificați magazinul, calea resursei și identificatorul. Folosiți identificatori returnați de acest magazin.
Reguli de reîncercare: Reîncercați numai după corectarea destinației sau confirmarea existenței acesteia.

JSON

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

405request.method_not_allowedEndpointul nu acceptă această metodă HTTP.

Ce trebuie făcut: Folosiți metoda documentată; antetul Allow indică metodele acceptate.
Reguli de reîncercare: Nu reîncercați metoda neacceptată.

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_reusedAceastă cheie de idempotență aparține unei alte cereri.

Ce trebuie făcut: Identificați operația originală. Folosiți o cheie nouă numai pentru o operație logică nouă, intenționată.
Reguli de reîncercare: Nu reîncercați date modificate folosind cheia aflată în conflict.

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_existsO valoare unică intră în conflict cu o resursă existentă.

Ce trebuie făcut: Citiți resursa existentă și decideți dacă o folosiți sau alegeți o altă valoare unică.
Reguli de reîncercare: Nu repetați aceeași creare aflată în conflict.

JSON

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

409resource.in_useAlte resurse depind încă de această resursă.

Ce trebuie făcut: Verificați dependențele și eliminați-le sau modificați-le prin operațiile acceptate înainte de ștergere.
Reguli de reîncercare: Reîncercați după rezolvarea dependențelor.

JSON

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

409resource.state_conflictStarea comercială curentă împiedică această modificare.

Ce trebuie făcut: Citiți starea curentă și alegeți o tranziție comercială validă.
Reguli de reîncercare: Nu forțați automat și nu retrimiteți repetat modificarea aflată în conflict.

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_conflictO altă scriere a modificat resursa după versiunea pe care ați citit-o.

Ce trebuie făcut: Citiți starea cea mai recentă, adaptați modificarea și trimiteți noua valoare expected_version.
Reguli de reîncercare: Folosiți o cheie de idempotență nouă pentru operația revizuită; nu suprascrieți fără verificare.

JSON

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

413request.too_largeCererea depășește limita de dimensiune.

Ce trebuie făcut: Reduceți datele trimise sau împărțiți operația în operații individuale acceptate.
Reguli de reîncercare: Reîncercați operații mai mici și valide, fiecare cu propria cheie de idempotență.

JSON

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

415request.unsupported_media_typeTipul media sau codificarea conținutului nu este acceptată.

Ce trebuie făcut: Pentru scrieri JSON, folosiți Content-Type: application/json și un corp necomprimat acceptat.
Reguli de reîncercare: Reîncercați după corectarea tipului media sau a codificării.

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_failedUnul sau mai multe câmpuri ori parametri nu trec validarea.

Ce trebuie făcut: Consultați error.fields, apoi verificați câmpurile obligatorii, acceptarea valorii null, identificatorii și valorile permise.
Reguli de reîncercare: Reîncercați o cerere corectată; o scriere modificată reprezintă o operație logică nouă.

JSON

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

429capacity.queue_fullCoada scurtă a API-ului este plină; executarea cererii nu a început.

Ce trebuie făcut: Puneți cererile într-o coadă și respectați antetul de răspuns Retry-After.
Reguli de reîncercare: Așteptați cel puțin numărul de secunde din Retry-After și adăugați o variație aleatorie. La reîncercarea unei scrieri, păstrați cheia și datele originale.

JSON

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

429capacity.wait_timeoutTimpul de așteptare în coada API-ului a expirat; executarea cererii nu a început.

Ce trebuie făcut: Puneți cererile într-o coadă și respectați antetul de răspuns Retry-After.
Reguli de reîncercare: Așteptați cel puțin numărul de secunde din Retry-After și adăugați o variație aleatorie. La reîncercarea unei scrieri, păstrați cheia și datele originale.

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.exceededFrecvența cererilor depășește limita aplicabilă.

Ce trebuie făcut: Puneți cererile într-o coadă și respectați antetul de răspuns Retry-After.
Reguli de reîncercare: Așteptați cel puțin numărul de secunde din Retry-After și adăugați o variație aleatorie. La reîncercarea unei scrieri, păstrați cheia și datele originale.

JSON

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

500internal.errorA apărut o eroare neașteptată a serviciului.

Ce trebuie făcut: Înregistrați identificatorul cererii și contactați operatorul dacă eroarea persistă; excludeți credențialele din jurnale.
Reguli de reîncercare: Folosiți reîncercări limitate, cu întârzieri progresive. Pentru scriere păstrați cheia de idempotență originală și datele neschimbate.

JSON

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

502gateway.bad_responseGateway-ul nu a primit un răspuns API valid.

Ce trebuie făcut: Păstrați identificatorul cererii. Un răspuns nereușit nu dovedește că scrierea nu a fost aplicată.
Reguli de reîncercare: Folosiți reîncercări limitate, cu întârzieri progresive; repetați aceeași scriere logică folosind valoarea Idempotency-Key și datele originale.

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 nu poate procesa temporar cererea.

Ce trebuie făcut: Respectați Retry-After când este prezent și păstrați identificatorul cererii dacă indisponibilitatea persistă.
Reguli de reîncercare: Folosiți reîncercări limitate, cu întârzieri progresive și variație aleatorie; păstrați cheia și datele la reîncercarea aceleiași scrieri.

JSON

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

504gateway.timeoutGateway-ul a depășit timpul de așteptare pentru API.

Ce trebuie făcut: Păstrați identificatorul cererii și considerați rezultatul scrierii necunoscut.
Reguli de reîncercare: Folosiți reîncercări limitate, cu întârzieri progresive; pentru scriere reutilizați cheia de idempotență originală și datele neschimbate.

JSON

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