Error Reference

Pientegra error envelope, External API'de dönen stable error code'lar ve retry kararları.

Pientegra hataları tek bir JSON envelope ile döner. Integration kodunda branching için message değil, error alanını kullan.

{
  "error": "validation_failed",
  "message": "Geçersiz istek.",
  "correlationId": "01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00",
  "details": {
    "issues": [
      {
        "path": ["targetIban"],
        "message": "Invalid string: must match pattern /^[A-Z0-9]{15,34}$/"
      }
    ]
  }
}

details.issues Zod-style array taşır: her hata path (alan yolu) ve human-readable message içerir. Tek bir request birden fazla issue döndürebilir.

retryAfterSeconds sadece 429 rate_limited response'larında bulunur (yukarıdaki örnekte yer almaz).

Field	Anlam
`error`	Stable, machine-readable code. Business logic burada branch etmeli.
`message`	Developer log'u için human-readable açıklama. Son kullanıcıya birebir göstermeyin.
`correlationId`	Pientegra support ile paylaşılacak trace ID.
`retryAfterSeconds`	Sadece rate limit response'larında bekleme süresi.
`details`	Validation gibi alan bazlı hatalarda ek context.

Authentication & tenancy

HTTP	`error`	Ne anlama gelir?
401	`unauthorized`	API key eksik, geçersiz, expired veya inactive.
403	`forbidden`	Request policy gereği reddedildi.
403	`tenant_inactive`	Partner hesabı veya site operasyonel olarak inactive.
403	`cross_tenant_denied`	API key'in scope'u dışındaki bir resource'a erişim denemesi.

Validation

HTTP	`error`	Ne anlama gelir?
400	`validation_failed`	Body veya required header contract'a uymuyor. `details` alanı field-bazlı hata listesi içerir.
400	`invalid_amount`	Amount formatı parse edilemedi.
400	`amount_below_min`	Amount partner için tanımlı minimum altında.
400	`amount_above_max`	Amount partner için tanımlı maximum üstünde.
400	`unsupported_currency`	Currency desteklenmiyor (varsayılan ve aktif: `TRY`).
404	`not_found`	Resource yok veya bu API key'in scope'u dışında.

Idempotency & state

HTTP	`error`	Ne anlama gelir?
409	`duplicate_idempotency_key`	Aynı `Idempotency-Key` ile aynı anda işlem sürüyor.
409	`idempotency_key_reuse_with_different_body`	Aynı key farklı payload ile tekrar kullanıldı.
409	`idempotency_key_expired`	Aynı key 24 saatlik TTL sonrası tekrar gönderildi; yeni bir key üretip tekrar deneyin.
409	`conflict`	Generic concurrency veya state conflict.
409	`invalid_state_transition`	Resource mevcut state'ten hedef state'e geçemez.
409	`collateral_exceeded`	Partner collateral limiti aşıldı; operasyonel aksiyon gerekir.

Capacity & infrastructure

HTTP	`error`	Ne anlama gelir?
429	`rate_limited`	Rate limit aşıldı. Cevap `retryAfterSeconds` içerir.
503	`all_accounts_capped`	Deposit için uygun aktif hesap kapasitesi kalmadı.
503	`service_unavailable`	Geçici dependency veya maintenance problemi.
500	`internal_error`	Beklenmeyen server-side hata.

Retry policy

POST request'lerinde retry yaparken aynı Idempotency-Key kullanılmalıdır. Yeni key ile retry etmek duplicate deposit veya withdrawal kaydı yaratabilir.

Durum	Aksiyon
Network timeout / connection reset	Aynı key ile retry.
`408`, `429`, `5xx`	Aynı key ile exponential backoff.
`duplicate_idempotency_key`	Kısa delay sonrası aynı key ile tekrar dene.
`validation_failed`, `unauthorized`, `forbidden`, `idempotency_key_reuse_with_different_body`	Retry yapma; request'i düzelt.

Idempotency TTL varsayılan olarak 24 saattir. Bu süre içinde aynı key ve aynı payload replay-safe davranır.