Hata Formatı

Tüm hata yanıtları RFC 7807 standardında, application/problem+json content-type ile döner.

Yanıt yapısı

Genel şema

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

Alan açıklamaları

Alan	Açıklama
`type`	Hata tipi URI'si (kategori belirleme için)
`title`	Kısa, sabit başlık
`status`	HTTP status code
`detail`	Bu spesifik hata için açıklama
`instance`	İsteğin geldiği path
`traceId`	Distributed tracing için W3C Trace-Parent değeri
`correlationId`	İstek korelasyon ID'si (log eşleştirme için)
`code`	Programatik karar için kullanılabilen kısa kod
`errors`	Validasyon hatalarında alan başına mesajlar (opsiyonel)

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	Açıklama
`validation-error`	Request validation (FluentValidation) hatası
`resource-not-found`	Path ile belirtilen ID'de kaynak yok veya size ait değil
`invalid-idempotency-key`	`Idempotency-Key` formatı uygun değil (max 64 char, alfanumerik + `-_`)
`forbidden`	Scope yetersiz
`conflict`	Domain state çakışması (örn. zaten cancelled order item)
`rate-limit-exceeded`	Hız limiti aşıldı
`upstream-unavailable`	Downstream servis erişilemez

Hata yönetimi örneği

Validasyon hatası örneği

400 Bad Request

{
  "type": "https://public-api.epinpark.com/problems/validation-error",
  "title": "Validation failed",
  "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, UpdatedAt, Price."]
  },
  "correlationId": "abc123",
  "traceId": "00-..."
}

correlationId nedir?

Her isteğe sunucu tarafından otomatik atanan benzersiz bir kimliktir. 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.