Hatalar
External Commerce API hata response'ları HTTP status, machine-readable error code, açıklayıcı message ve request_id üzerinden işlenmelidir.
| HTTP | Anlamı | İlk yapmanız gereken |
|---|---|---|
| 400 | Bad Request | Request/header yapısını kontrol edin |
| 401 | Unauthorized | Credential'ı kontrol edin |
| 403 | Forbidden | Scope yetkisini kontrol edin |
| 404 | Not Found | Resource ID ve tenant kapsamını kontrol edin |
| 409 | Conflict | error.code ve idempotency durumunu inceleyin |
| 422 | Validation Error | Gönderdiğiniz alanları düzeltin |
| 500 | Server Error | request_id saklayıp kontrollü retry değerlendirin |
Bir hata aldığınızda önce ne yapmalısınız?
İlk olarak HTTP status değerini okuyun. Ardından response içerisindeki error.code ve error.message alanlarını kontrol edin.
request_id değerini mutlaka teknik logunuza kaydedin. Bu değer belirli API isteğini daha sonra izleyebilmek için kullanılır.
Standart error response
{
"success": false,
"error": {
"code": "product_not_found",
"message": "Ürün bulunamadı."
},
"request_id": "req_xxxxxxxx"
}401 Unauthorized
Credential gönderilmemiş, yanlış, revoke edilmiş veya authentication için kullanılamıyor olabilir.
401 hatasını sürekli retry etmeyin. Authorization header ve credential yapılandırmasını düzeltin.
403 Forbidden
Credential geçerlidir ancak endpoint için gerekli scope yetkisine sahip değildir.
Örneğin stok yazmak için inventory:write yetkisi gerekir. Credential'ın aktif scope listesini kontrol etmek için health endpointini kullanabilirsiniz.
404 Not Found
İstenen resource gerçekten bulunmayabilir veya resource credential'ın tenant kapsamı dışında olabilir.
Başka mağazaya geçmek için request'e store_id eklemeye çalışmayın. Tenant credential tarafından belirlenir.
409 Conflict
Conflict çoğunlukla idempotency veya resource state nedeniyle oluşur. error.code alanını okuyarak gerçek nedeni ayırın.
- Aynı Idempotency-Key farklı payload ile kullanılmış olabilir.
- Aynı idempotent request halen işleniyor olabilir.
- Varyantlı üründe ürün seviyesinde stok veya fiyat yazmaya çalışılmış olabilir.
422 Validation Error
Request JSON yapısı syntactically geçerli olsa bile business veya field validation başarısız olabilir.
Zorunlu alan eksikliği, yanlış veri tipi, desteklenmeyen değer veya caller-controlled store_id gibi contract ihlalleri 422 oluşturabilir.
500 Server Error
Beklenmeyen backend hatasını ifade eder. request_id değerini kaydedin. Aynı request write işlemi ise retry öncesinde idempotency davranışını dikkate alın.
5xx hatalarında kısa süreli exponential backoff ile kontrollü retry uygulanabilir; sınırsız retry döngüsü oluşturmayın.
Retry matrisi
| HTTP | Otomatik retry? | Ne yapmalısınız? |
|---|---|---|
| 400 | Hayır | Request'i düzeltin |
| 401 | Hayır | Credential'ı düzeltin |
| 403 | Hayır | Scope'u düzeltin |
| 404 | Hayır | Resource/tenant bilgisini kontrol edin |
| 409 | Duruma bağlı | error.code inceleyin |
| 422 | Hayır | Validation problemini düzeltin |
| 500 | Kontrollü | Exponential backoff değerlendirin |
Loglarda ne saklamalıyım?
- request_id
- HTTP status
- error.code
- endpoint path
- HTTP method
- timestamp
- Idempotency-Key kullanıldıysa key değeri
Destek isterken
Beklenmeyen bir hatayı bildirirken credential paylaşmayın. request_id, yaklaşık istek zamanı, endpoint, HTTP method ve HTTP status bilgilerini paylaşmanız yeterlidir.