Hatalar ve kurtarma

Düzeltme, bekleme veya yeniden deneme kararını kararlı hata kodlarına göre verin.

Yapılması gerekenler

Program akışını insan tarafından okunabilir error.message yerine HTTP durumu ve error.code değerine göre belirleyin.
401 geçerli kimlik doğrulaması, 403 erişim veya plan değişikliği, 409 ise çakışan işlemin veya kaynak sürümünün kontrol edilmesini gerektirir.

Erişim reddi ve yeniden deneme

401: 401 her zaman tokenın süresinin dolduğu anlamına gelmez. Süresi dolduysa yenisini alın ve okuma isteğini en fazla bir kez tekrarlayın. Token alma isteği 401 döndürürse anahtarı kontrol edin ve otomatik denemeleri durdurun.
403: 403 durumunda izinleri, IP kısıtlamalarını ve planı kontrol edin. Yeni token, iptal edilen erişimi geri getirmez.

Kimlik doğrulama

Yeniden deneme ilkesi

Geçici hatalarda deneme sayısını sınırlayın, bekleme süresini artırın ve rastgele gecikme ekleyin.
Verilmişse Retry-After değerine uyun.
Bir yazma isteği zaman aşımına uğradığında sonucu bilinmeyebilir: aynı mantıksal işlemi yeniden denerken aynı Idempotency-Key değerini ve değiştirilmemiş isteği koruyun.
Aşağıdaki katalog yayımlanmış her hata kodunu açıklar.

Güvenli yazma işlemleri

İstek hızı sınırları

422 / 409

Fiyatlarda geçersiz para birimi biçimi veya tutar hassasiyeti 422 request.validation_failed döndürür.
Seçilen fiyat listesinden farklı olan geçerli bir para birimi kodu 409 resource.version_conflict döndürür.
Yeniden denemeden önce bağlamı ve sürümleri kontrol edin.

Hata kataloğu

400request.malformedİstek ayrıştırılamıyor.

Yapılması gerekenler: JSON sözdizimini, URL kodlamasını ve istek yapısını kontrol edin.
Yeniden deneme ilkesi: İsteği düzelttikten sonra deneyin.

JSON

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

401authentication.invalid_credentialsAPI anahtarı veya erişim belirteci geçersiz, süresi dolmuş ya da iptal edilmiş.

Yapılması gerekenler: Mağaza URL'sini ve kimlik bilgisini kontrol edin. Etkin bir API anahtarıyla yeni belirteç alın.
Yeniden deneme ilkesi: Kimlik doğrulamayı düzelttikten sonra deneyin; geçersiz belirteç isteklerini tekrarlamayın.

JSON

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

401authentication.requiredGerekli Authorization başlığı yok veya şeması yanlış.

Yapılması gerekenler: Belirteç isterken ApiKey, kaynak işlemlerinde Bearer kullanın.
Yeniden deneme ilkesi: Doğru başlığı ekledikten sonra deneyin.

JSON

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

403authorization.client_ip_unverifiedHizmet, güvenilir bir istemci IP adresi belirleyemedi.

Yapılması gerekenler: Mağaza işletmeninden giriş bağlantısını kontrol etmesini isteyin. Yönlendirme başlıklarını kendiniz eklemeyin.
Yeniden deneme ilkesi: Güvenilir bağlantı yolu yeniden sağlandıktan sonra deneyin.

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_allowedKaynak IP adresi, anahtarın izin verilen adresler listesinde değil.

Yapılması gerekenler: Onaylı bir kaynak adres kullanın veya yetkili yöneticiden anahtarın IP listesini düzenlemesini isteyin.
Yeniden deneme ilkesi: Yalnızca adrese izin verildikten sonra deneyin.

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_deniedAnahtar, bu işlem için gereken geçerli izne sahip değil.

Yapılması gerekenler: İşlemin zorunlu ve koşullu izinlerini, anahtara verilen izinleri ve anahtarı oluşturan kişinin erişimini kontrol edin.
Yeniden deneme ilkesi: Yetkili yönetici gerekli erişimi verdikten sonra deneyin.

JSON

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

403entitlements.api_disabledBu mağazada API erişimi kapalı.

Yapılması gerekenler: Mağaza sahibinden etkin planı ve API kullanılabilirliğini kontrol etmesini isteyin.
Yeniden deneme ilkesi: API erişimi açılana kadar yeniden denemeyin.

JSON

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

403entitlements.limit_exceededDeğişiklik, mevcut planın bir sınırını aşacak.

Yapılması gerekenler: Geçerli kaynak sınırını kontrol edip planlanan değişikliği veya planı ayarlayın.
Yeniden deneme ilkesi: Sınır sorununu çözdükten sonra deneyin; istek değişirse yeni idempotans anahtarı kullanın.

JSON

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

403entitlements.operation_disabledMevcut plan bu işlemi içermiyor.

Yapılması gerekenler: İşlem için belirtilen en düşük planı kontrol edin.
Yeniden deneme ilkesi: Plan işleme izin verdiğinde ve anahtar gerekli izinlere sahip olduğunda deneyin.

JSON

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

403entitlements.resource_blockedBir plan sınırı bu kaynağı engelliyor.

Yapılması gerekenler: Mağaza sahibinden kaynağın plan kısıtlamasını çözmesini isteyin.
Yeniden deneme ilkesi: Kaynak engelliyken aynı isteği tekrarlamayın.

JSON

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

404resource.not_foundKaynak yok, silinmiş veya verilen tanımlayıcıyla erişilemiyor.

Yapılması gerekenler: Mağazayı, kaynak yolunu ve tanımlayıcıyı kontrol edin. Bu mağazanın döndürdüğü tanımlayıcıları kullanın.
Yeniden deneme ilkesi: Yalnızca hedefi düzelttikten veya var olduğunu doğruladıktan sonra deneyin.

JSON

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

405request.method_not_allowedUç nokta bu HTTP yöntemini desteklemiyor.

Yapılması gerekenler: Belgelenen yöntemi kullanın; Allow başlığı desteklenen yöntemleri belirtir.
Yeniden deneme ilkesi: Desteklenmeyen yöntemi tekrar denemeyin.

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_reusedBu idempotans anahtarı farklı bir isteğe ait.

Yapılması gerekenler: Özgün işlemi bulun. Yeni anahtarı yalnızca bilinçli olarak yeni bir mantıksal işlem için kullanın.
Yeniden deneme ilkesi: Değiştirilmiş gövdeyi çakışan anahtarla tekrar göndermeyin.

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_existsBenzersiz bir değer mevcut kaynakla çakışıyor.

Yapılması gerekenler: Mevcut kaynağı okuyup onu kullanmaya veya farklı bir benzersiz değer seçmeye karar verin.
Yeniden deneme ilkesi: Aynı çakışan oluşturma işlemini tekrarlamayın.

JSON

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

409resource.in_useBaşka kaynaklar hâlâ bu kaynağa bağımlı.

Yapılması gerekenler: Bağımlılıkları inceleyin; silmeden önce desteklenen işlemlerle kaldırın veya değiştirin.
Yeniden deneme ilkesi: Bağımlılıkları çözdükten sonra deneyin.

JSON

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

409resource.state_conflictMevcut iş durumu bu değişikliği engelliyor.

Yapılması gerekenler: Geçerli durumu okuyup izin verilen bir iş durumu geçişi seçin.
Yeniden deneme ilkesi: Çakışan değişikliği otomatik olarak zorlamayın veya tekrar tekrar göndermeyin.

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_conflictBaşka bir yazma, okuduğunuz sürümden sonra kaynağı değiştirdi.

Yapılması gerekenler: En güncel durumu okuyun, değişikliğinizi uyarlayın ve yeni expected_version gönderin.
Yeniden deneme ilkesi: Gözden geçirilmiş işlem için yeni idempotans anahtarı kullanın; kontrol etmeden üzerine yazmayın.

JSON

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

413request.too_largeİstek boyut sınırını aşıyor.

Yapılması gerekenler: Gövdeyi küçültün veya işi desteklenen ayrı işlemlere bölün.
Yeniden deneme ilkesi: Daha küçük, geçerli işlemleri kendi idempotans anahtarlarıyla deneyin.

JSON

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

415request.unsupported_media_typeMedya türü veya içerik kodlaması desteklenmiyor.

Yapılması gerekenler: JSON yazmaları için Content-Type: application/json ve desteklenen sıkıştırılmamış gövde kullanın.
Yeniden deneme ilkesi: Medya türünü veya kodlamayı düzelttikten sonra deneyin.

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_failedBir veya daha fazla alan ya da parametre doğrulamadan geçemedi.

Yapılması gerekenler: error.fields alanını inceleyin; zorunlu alanları, null kabulünü, tanımlayıcıları ve izin verilen değerleri kontrol edin.
Yeniden deneme ilkesi: Düzeltilmiş isteği deneyin; değiştirilmiş bir yazma yeni bir mantıksal işlemdir.

JSON

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

429capacity.queue_fullKısa API kuyruğu dolu; isteğin yürütülmesi başlamadı.

Yapılması gerekenler: İstekleri kuyruğa alın ve yanıttaki Retry-After başlığına uyun.
Yeniden deneme ilkesi: En az Retry-After saniye bekleyip rastgele gecikme ekleyin. Yazmayı tekrarlarken özgün anahtarı ve gövdeyi koruyun.

JSON

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

429capacity.wait_timeoutAPI kuyruğunda bekleme süresi doldu; isteğin yürütülmesi başlamadı.

Yapılması gerekenler: İstekleri kuyruğa alın ve yanıttaki Retry-After başlığına uyun.
Yeniden deneme ilkesi: En az Retry-After saniye bekleyip rastgele gecikme ekleyin. Yazmayı tekrarlarken özgün anahtarı ve gövdeyi koruyun.

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.exceededİstek sıklığı geçerli sınırı aşıyor.

Yapılması gerekenler: İstekleri kuyruğa alın ve yanıttaki Retry-After başlığına uyun.
Yeniden deneme ilkesi: En az Retry-After saniye bekleyip rastgele gecikme ekleyin. Yazmayı tekrarlarken özgün anahtarı ve gövdeyi koruyun.

JSON

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

500internal.errorBeklenmeyen bir hizmet hatası oluştu.

Yapılması gerekenler: İstek tanımlayıcısını kaydedin; hata sürerse işletmene başvurun. Kimlik bilgilerini günlüklere yazmayın.
Yeniden deneme ilkesi: Sınırlandırılmış artan bekleme kullanın. Yazmada özgün idempotans anahtarını ve değişmemiş gövdeyi koruyun.

JSON

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

502gateway.bad_responseAğ geçidi geçerli bir API yanıtı alamadı.

Yapılması gerekenler: İstek tanımlayıcısını saklayın. Başarısız yanıt, yazma işleminin uygulanmadığını kanıtlamaz.
Yeniden deneme ilkesi: Sınırlandırılmış artan bekleme kullanın; aynı mantıksal yazmayı özgün Idempotency-Key ve gövdesiyle tekrarlayın.

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 şu anda isteği işleyemiyor.

Yapılması gerekenler: Varsa Retry-After başlığına uyun; kesinti sürerse istek tanımlayıcısını saklayın.
Yeniden deneme ilkesi: Rastgele gecikmeyle sınırlandırılmış artan bekleme kullanın; aynı yazmayı tekrarlarken anahtarı ve gövdeyi koruyun.

JSON

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

504gateway.timeoutAğ geçidi API'yi beklerken zaman aşımına uğradı.

Yapılması gerekenler: İstek tanımlayıcısını saklayın ve yazma işleminin sonucunu belirsiz kabul edin.
Yeniden deneme ilkesi: Sınırlandırılmış artan bekleme kullanın; yazmada özgün idempotans anahtarını ve değişmemiş gövdeyi koruyun.

JSON

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