> ## Documentation Index
> Fetch the complete documentation index at: https://docs.banka.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Yanıtlar ve hatalar

> Başarı ve hata zarfı, izleme kimliği, kısmi yanıtlar ve hata kodları.

## Başarı zarfı

```json theme={null}
{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "9cc0d3d1-1e63-4c90-b08f-90b6332e70ca",
    "timestamp": "2026-09-08T20:00:00.000Z"
  }
}
```

| Alan | Açıklama |
| - | - |
| `data` | Uca göre nesne veya dizi |
| `meta.requestId` | İsteğin izleme kimliği; `x-request-id` başlığıyla aynıdır |
| `meta.timestamp` | Yanıtın üretildiği an (UTC) |
| `meta.page`, `meta.pageSize`, `meta.total`, `meta.totalPages` | Yalnız liste uçlarında. Bkz. [Sayfalama ve filtreler](/sayfalama-ve-filtreler) |
| `meta.partial` | `true` ise yanıt eksik veri içerir |
| `meta.warnings` | Eksikliğin nedenini anlatan uyarılar |

### Kısmi yanıtlar ve uyarılar

Bakiye her hesap için bilinmeyebilir. Bu durumda istek yine başarılı döner ve `meta.warnings` durumu açıklar; veri eksikse `meta.partial` ayrıca `true` olur. Uyarı taşıyan yanıtı eksiksiz veri gibi işlemeyin.

```json theme={null}
"meta": {
  "partial": true,
  "warnings": [
    { "code": "BALANCE_VALUE_UNKNOWN", "message": "…", "accountCount": 2 }
  ]
}
```

| Uyarı kodu | Anlamı |
| - | - |
| `BALANCE_VALUE_UNKNOWN` | Doğrulanmış bakiyesi bulunmayan hesaplar toplamlara dahil edilmedi |
| `BALANCE_VALUE_STALE` | Son hareket bakiye bilgisi taşımadığı için önceki doğrulanmış bakiye kullanıldı |
| `BALANCE_CURRENCY_MISMATCH` | Hesabın para birimiyle eşleşen bir hareket bakiyesi bulunamadı |
| `INVALID_ACCOUNT_CURRENCY` | Para birimi kodu geçersiz olan hesaplar bakiye toplamlarına dahil edilmedi |

Tanımadığınız bir uyarı kodu gelirse onu da bir veri eksikliği işareti olarak ele alın.

## Hata zarfı

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "pageSize 1-100 araliginda olmalidir.",
    "details": [{ "field": "pageSize", "rule": "min:1,max:100" }]
  },
  "traceId": "9cc0d3d1-1e63-4c90-b08f-90b6332e70ca"
}
```

* Programınızın karar verirken `error.code` değerini kullanın; `error.message` insan için yazılmıştır ve değişebilir.
* `error.details` doğrulama hatalarında hangi alanın hangi kuralı ihlal ettiğini listeler; diğer hatalarda boş dizidir.
* `traceId`, destek talebinde paylaşmanız gereken kimliktir.

## Hata kodları

| HTTP | Kod | Ne zaman |
| - | - | - |
| 400 | `VALIDATION_FAILED` | Parametre veya gövde kurallara uymuyor; ayrıntı `details` içinde |
| 400 | `INVALID_JSON` | Gövde geçerli JSON değil |
| 400 | `TENANT_SELECTOR_FORBIDDEN` | İstekte firma seçmeye çalışan başlık veya parametre var. Bkz. [Firma bağlamı](/kimlik-dogrulama#firma-bağlamı) |
| 401 | `UNAUTHORIZED` | Kimlik bilgisi yok, yanlış, anahtar pasif veya süresi dolmuş |
| 403 | `FORBIDDEN` | Anahtarın bu uç için yetkisi yok |
| 403 | `API_IP_FORBIDDEN` | İstek, anahtarın IP kısıtı dışındaki bir adresten geldi |
| 403 | `API_PRODUCT_FORBIDDEN` | Anahtarın BankaPro erişimi yok |
| 403 | `API_COMPANY_FORBIDDEN` | Firmanın BankaPro erişimi yok veya etkin değil |
| 403 | `CORS_FORBIDDEN` | İstek tarayıcıdan (`Origin` başlığıyla) geldi |
| 404 | `RESOURCE_NOT_FOUND` | Kaynak yok ya da firmanıza ait değil |
| 413 | `PAYLOAD_TOO_LARGE` | Gövde izin verilen boyutu aşıyor |
| 429 | `RATE_LIMITED` | İstek limiti aşıldı. Bkz. [Limitler](/limitler) |
| 500 | `INTERNAL_ERROR` | Beklenmeyen sunucu hatası |

<Note>
  Başka bir firmaya ait hesap veya hareket kimliğiyle yapılan istek `404` döner; kaydın var olup olmadığı açıklanmaz.
</Note>

## İzleme kimliği (`x-request-id`)

Her yanıtta `x-request-id` başlığı bulunur. İsteğinizde kendi kimliğinizi gönderebilirsiniz: değer 1–100 karakterse ve yalnız harf, rakam, nokta, alt çizgi, iki nokta veya tire içeriyorsa korunur, aksi halde sunucu yeni bir UUID üretir. Kendi log kayıtlarınızla eşleştirmek için bu kimliği saklayın.

```bash theme={null}
curl https://api.banka.pro/v1/bank-transactions \
  -u "$BANKAPRO_API_KEY_ID:$BANKAPRO_API_SECRET" \
  -H "x-request-id: erp-sync-2026-09-08-001"
```

## Önbellek

Bütün yanıtlar `Cache-Control: no-store` taşır. Banka verisini ara katmanlarda (CDN, proxy) önbelleğe almayın.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.