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

# Hata Yanıtları

> Flextell API'deki hata yapısını, HTTP status code'larını ve doğrulama hatalarının okunmasını öğrenin.

Flextell yanıtlarının hepsi JSON'dur ve başarı ya da başarısızlığı `success` alanı üzerinden işaretler.

## Başarı yanıtı

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

Liste uçlarında `data` bir dizi, `links` ve `meta` da bulunur — bkz. [Sayfalama](/requests/pagination).

## Hata yanıtı

```json theme={null}
{
  "success": false,
  "error": "Tenant not found.",
  "data": {
    "message": "Tenant not found."
  }
}
```

Doğrulama hatalarında ek olarak alanlara göre kırılım verilir:

```json theme={null}
{
  "success": false,
  "error": "The given data was invalid.",
  "data": {
    "message": "The given data was invalid."
  },
  "errors": {
    "email": ["The email field is required."],
    "phone_number": ["The phone number format is invalid."]
  }
}
```

<ResponseField name="success" type="boolean">
  Hata yanıtlarında her zaman `false`.
</ResponseField>

<ResponseField name="error" type="string">
  Kısa, insan-okunur hata mesajı. UI'da göstermek için uygundur.
</ResponseField>

<ResponseField name="errors" type="object">
  Yalnızca 422 doğrulama hatalarında bulunur. Alan adından hata mesajları dizisine doğru bir map'tir.
</ResponseField>

## HTTP status kodları

| Kod                         | Anlamı                                                       | Ne yapmalı?                                                                    |
| --------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| `200 OK`                    | Başarılı okuma                                               | —                                                                              |
| `201 Created`               | Kaynak oluşturuldu                                           | Dönen `data`'daki ID'yi saklayın                                               |
| `204 No Content`            | Başarılı silme                                               | Yanıt gövdesi yoktur                                                           |
| `400 Bad Request`           | Geçersiz JSON, eksik `X-Tenant`                              | İstek gövdesini ve header'larını kontrol edin                                  |
| `401 Unauthorized`          | Token yok, geçersiz veya süresi dolmuş                       | Token yenilemeyi deneyin; başarısızsa yeniden yetkilendirin                    |
| `403 Forbidden`             | Token'ın scope'u yetersiz veya kullanıcının permission'ı yok | [Scopes](/authentication/scopes) ve [Roller](/tenancy/roles) sayfalarına bakın |
| `404 Not Found`             | Kaynak yok veya kullanıcının o tenant'a/kayda erişimi yok    | ID ve tenant'ı doğrulayın                                                      |
| `409 Conflict`              | Çakışan değişiklik (nadiren)                                 | Mevcut kaydı tekrar çekip işlem yapın                                          |
| `422 Unprocessable Entity`  | Doğrulama hatası                                             | `errors` nesnesini okuyup alan alan gösterin                                   |
| `429 Too Many Requests`     | Rate limit aşıldı                                            | `Retry-After` header'ına göre bekleyin                                         |
| `500 Internal Server Error` | Sunucu tarafı beklenmeyen hata                               | Biraz bekleyip tekrar deneyin; sürerse [destek](/resources/support)            |
| `503 Service Unavailable`   | Bakım / geçici kesinti                                       | `Retry-After` header'ı varsa ona uyun                                          |

## Yaygın hata senaryoları

### Token süresi doldu

```
HTTP/1.1 401 Unauthorized
```

Refresh token'ınızı kullanarak yenisini alın. Detay: [Token Yenileme](/authentication/refresh-tokens).

### `X-Tenant` unutuldu

```json theme={null}
{
  "success": false,
  "error": "X-Tenant header is required."
}
```

İsteğinize `X-Tenant` header'ını ekleyin. Detay: [Multi-Tenancy](/tenancy/overview).

### Scope yetersiz

```
HTTP/1.1 403 Forbidden
```

Kullanıcının uygulamanıza verdiği yetki o uç için yeterli değildir. Örneğin `POST /customers` için `customers:write` scope'u gerekir. Token'ınızın scope listesini [Scopes](/authentication/scopes) ile karşılaştırın; gerekli scope'u uygulama oluştururken eklemediyseniz yeni bir uygulama oluşturmanız gerekir.

### Doğrulama hatası (422)

```json theme={null}
{
  "success": false,
  "error": "The given data was invalid.",
  "errors": {
    "phone_number": ["The phone number has already been taken."]
  }
}
```

UI'da alan bazlı hata gösterin. Kullanıcı telefon numarasını düzenlesin ve isteği tekrar göndersin.

## Hata yönetimi önerisi

```js theme={null}
async function call(endpoint, options) {
  const res = await fetch(endpoint, options);
  const body = await res.json().catch(() => ({}));

  if (res.ok) {
    return body.data;
  }

  if (res.status === 401) {
    await refreshTokens();
    return call(endpoint, options);
  }

  if (res.status === 422) {
    throw new ValidationError(body.error, body.errors);
  }

  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") || 1);
    await sleep(wait * 1000);
    return call(endpoint, options);
  }

  throw new ApiError(res.status, body.error || "Unknown error");
}
```