Hata Formatı

Bir uç noktaya ulaşan isteklerin hata yanıtları RFC 7807 standardında, application/problem+json content-type ile döner.

Gövdesiz dönen durumlar

401, 403, bilinmeyen yola atılan 404 ve desteklenmeyen metotta 405 yanıt gövdesiz gelir; ayrıntı yalnızca HTTP durum kodudur.

401 ve 403'te bu kasıtlıdır: imzanın mı, zaman damgasının mı, yoksa anahtarın kendisinin mi sorunlu olduğunu söylemek, anahtarın sistemde var olup olmadığını dışarıya sızdırır. Bu yüzden bütün kimlik doğrulama hataları birbirinden ayırt edilemez. Hangi uç noktanın hangi scope'u istediği İzinler sayfasında listelidir; 403 alıyorsanız anahtarınızın yetkilerini oradan karşılaştırın.

İstemcinizde gövdeyi ayrıştırmadan önce boş olup olmadığını kontrol edin.

Yanıt yapısı

Genel şema

{
  "type": "https://api.epinpark.com/problems/<kod>",
  "title": "Kısa, insan okunabilir başlık",
  "status": 400,
  "detail": "Spesifik açıklama",
  "code": "validation-error",
  "errors": {
    "Page": ["Page must be greater than or equal to 1."]
  }
}

Alan açıklamaları

Alan	Her yanıtta	Açıklama
`type`	evet	Hata tipi URI'si (kategori belirleme için)
`title`	evet	Kısa, sabit başlık
`status`	evet	HTTP status code
`code`	hayır	Programatik karar için kısa kod. İş kuralı ve kaynak hatalarında bulunur; parametre doğrulama hatalarında (`400`) bulunmaz — orada `errors` alanına bakın
`detail`	hayır	Bu spesifik hata için açıklama
`errors`	hayır	Parametre doğrulama hatalarında alan başına mesajlar
`instance`, `traceId`, `correlationId`	hayır	Bazı yanıtlarda bulunur; korelasyon için `X-Request-Id` yanıt header'ını kullanın — o her yanıtta var

Parametre doğrulama hatasının tipi farklı

Sayfalama, sıralama ve filtre parametrelerindeki hatalar (400) type alanında RFC 9110 bağlantısı taşır ve code içermez; anlatan alan errors'tur. Diğer bütün hatalarda type yukarıdaki https://api.epinpark.com/problems/<code> biçimindedir.

HTTP status code'lar

Code	Anlam	Tipik kullanım
`400`	Bad Request	Validasyon hatası (eksik/yanlış parametre)
`401`	Unauthorized	HMAC header eksik, imza hatalı, timestamp tolerans dışı
`403`	Forbidden	API key'de gerekli scope yok
`404`	Not Found	Kaynak bulunamadı veya başka bir satıcıya ait
`409`	Conflict	Mevcut state ile çakışma (örn. zaten fulfilled sipariş)
`413`	Payload Too Large	Multipart upload sınırı aşıldı
`422`	Unprocessable Entity	Domain validation hatası
`429`	Too Many Requests	Hız sınırı aşıldı (`Retry-After` header'ı var)
`500`	Internal Server Error	Beklenmedik sunucu hatası
`502`	Bad Gateway	Downstream servisten geçersiz yanıt
`503`	Service Unavailable	Downstream servise ulaşılamıyor

404 ile 403 ayrımı

Başka bir satıcıya ait bir kaynağa erişmeye çalıştığınızda yanıt 403 değil 404 döner. Bu kasıtlıdır — kaynağın varlığını veya sahibini sızdırmamak için.

Hata tipleri kataloğu

Type URI sonu	Status	Açıklama
`invalid-idempotency-key`	400	`Idempotency-Key` formatı uygun değil (max 64 char, alfanumerik + `-_`)
`resource-not-found`	404	Path ile belirtilen ID'de kaynak yok veya size ait değil
`conflict`	409	Domain state çakışması (örn. zaten cancelled order item)
`domain-rule-violation`	422	İş kuralı ihlali
`rate-limit-exceeded`	429	Hız limiti aşıldı
`internal-error`	500	Beklenmedik sunucu hatası
`upstream-unavailable`	502/503/504	Downstream servis erişilemez

İş kuralına özgü kodlar

409 ve 422 yanıtlarında code alanı yukarıdaki genel değerler yerine kuralın kendi adını taşıyabilir — örneğin invoice-already-exists, claim-not-waiting-seller, order-item-not-cancellable. Bunlar da aynı biçimdedir: type alanı https://api.epinpark.com/problems/<code> olur. Karar verirken code alanını kullanın; title ve detail insan okunabilir metinlerdir ve değişebilir.

Hata yönetimi örneği

Validasyon hatası örneği

400 Bad Request

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "page": ["Page must be greater than or equal to 1."],
    "pageSize": ["PageSize must be between 10 and 100."],
    "orderBy": ["OrderBy must be one of: CreatedAt."]
  }
}

correlationId nedir?

Her isteğe sunucu tarafından otomatik atanan benzersiz bir kimliktir ve X-Request-Id yanıt header'ında döner. Hata raporlarken bu değeri paylaşın — Epinpark loglarından isteğinizi 1 saniyede bulabiliriz.

Kendi correlation ID'nizi de gönderebilirsiniz:

X-Request-Id: my-app-trace-abc123

Bu durumda yanıt header'ında da aynı değer döner.