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

# Hata İşleme

> GOWA'nın yanıt zarfı, hata kodları ve HTTP durumları ile bunların nasıl ele alınacağı.

## Yanıt zarfı

Her JSON yanıtı aynı yapıya sahiptir:

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": { }
}
```

| Alan | Açıklama |
| - | - |
| `code` | `SUCCESS` veya bir hata kodu. İşlem dalını seçmek için HTTP durumuyla birlikte bunu kullanın. |
| `message` | İnsanların okuyabileceği ayrıntı. İfade biçimi sürümler arasında değişebilir; programatik olarak ayrıştırmayın. |
| `results` | Başarı durumunda veri yükü. Hatalarda genellikle bulunmaz. |

## Hata kodları

| Kod | HTTP | Anlamı | Ne yapılmalı |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | Eksik veya geçersiz alan. `message` alanı bunu belirtir. | İsteği düzeltin. |
| `INVALID_JID` | 400 | Numara WhatsApp'ta değil veya JID biçimi hatalı. | Numarayı kontrol edin; yeniden denemeyin. |
| `ALREADY_LOGGED_IN` | 400 | Zaten oturum açmış bir cihaz için giriş istendi. | Bir şey yapmayın veya önce oturumu kapatın. |
| `DEVICE_ID_REQUIRED` | 400 | Cihaz belirtilmedi ve sunucuda sıfır veya birden fazla cihaz var. | `X-Device-Id` gönderin. |
| `AUTHENTICATION_ERROR` | 401 | Cihaz WhatsApp'ta oturum açmamış (veya WhatsApp kimlik doğrulaması başarısız). | `/devices/{id}/status` yolunu kontrol edin; gerekirse yeniden eşleştirin. |
| `NOT_FOUND` | 404 | Kaynak bulunamadı (mesaj, sohbet, zamanlama…). | Kimliği kontrol edin. |
| `DEVICE_NOT_FOUND` | 404 | `X-Device-Id` bilinmeyen bir cihazı belirtiyor. | Yuva kimliğini veya JID'yi kontrol edin. |
| `AVATAR_HIDDEN` | 403 | Profil resmi gizlilik ayarlarıyla gizlenmiş. | Bunu resmin kesinlikle bulunmadığı şeklinde değerlendirmeyin veya yalnızca bu sonuca dayanarak önbellekteki resmi silmeyin. |
| `AVATAR_NOT_SET` | 404 | Kişinin profil resmi yok. | Önbellekteki resmi herhangi bir 404'te değil, yalnızca bu kodu kontrol ettikten sonra temizleyin. |
| `CROSS_SITE_REQUEST_BLOCKED` | 403 | Tarayıcı kaynağı güvenilir değil. | Panoyu HTTP(S) üzerinden sunun ve güvenilen kaynağı tam olarak yapılandırın. |
| `CONTEXT_ERROR` | 408 | İşlem dahili olarak iptal edildi veya zaman aşımına uğradı. | Bir kez yeniden deneyin. |
| `WA_REACHOUT_TIMELOCK` | 429 | WhatsApp bu hesaptan yeni sohbetleri geçici olarak engelliyor. | Yeni kişilere gönderimi durdurun; bkz. [Gönderim sınırları](https://gowa-docs.mintlify.site/tr/advanced/rate-limiting.md). |
| `INTERNAL_SERVER_ERROR` | 500 | Kurtarılan panikler dahil beklenmeyen hata. | Artan bekleme süreleriyle yeniden deneyin; günlükleri kontrol edin. |
| `QR_CHANNEL_ERROR` | 500 | QR kodu alınamadı. | Girişi yeniden deneyin. |
| `SESSION_SAVED_ERROR` | 500 | Oturum kalıcı olarak kaydedilemedi. | Depolamayı ve izinleri kontrol edin. |
| `UPLOAD_MEDIA_ERROR` | 500 | WhatsApp'a medya yükleme başarısız. | Yeniden deneyin; boyut ve biçimi kontrol edin. |
| `WEBHOOK_ERROR` | 500 | Webhook yapılandırma veya teslim hatası. | Webhook URL'sini kontrol edin. |
| `INVALID_WA_CLI` | 500 | Cihazın WhatsApp istemcisi başlatılmamış. | Yeniden bağlanın veya tekrar giriş yapın. |
| `DEVICE_MANAGER_UNAVAILABLE` | 503 | Cihaz yöneticisi başlatılmamış. | Kısa süre sonra yeniden deneyin; başlangıç günlüklerini kontrol edin. |
| `GATEWAY_TIMEOUT` | 504 | İstek 45 saniyeyi aştı. | İşlem yine de tamamlanabilir; yeniden denemeden önce kontrol edin. |

Basic Auth hataları GOWA işleyicilerine ulaşmadan kimlik doğrulama katmanından `401` döndürür; `401` yanıtlarını, GOWA `code` değeri yoksa hatalı kimlik bilgileri olarak değerlendirin.

## Güvenli yeniden deneme

Gönderim **idempotent değildir**: GOWA'da idempotentlik anahtarı yoktur. Bir gönderim zaman aşımına uğrarsa (`504`, ağ hatası), mesaj zaten teslim edilmiş olabilir. Yeniden göndermeden önce `GET /chat/{chat_jid}/messages?is_from_me=true&limit=5` ile sohbeti kontrol edin veya yinelenen mesaj riskini kabul edin.

| Yeniden deneyin | Yeniden denemeyin |
| - | - |
| `500 INTERNAL_SERVER_ERROR`, `UPLOAD_MEDIA_ERROR`, `CONTEXT_ERROR`, `503` | `400` hataları, `INVALID_JID`, `404`, `401`, `WA_REACHOUT_TIMELOCK` |

Üst sınırı olan üstel bekleme kullanın ve deneme sayısını sınırlayın.

```javascript theme={null}
async function gowa(path, body, attempt = 1) {
  const res = await fetch(`http://localhost:3000${path}`, {
    method: "POST",
    headers: {
      Authorization: "Basic " + Buffer.from("admin:changeme").toString("base64"),
      "Content-Type": "application/json",
      "X-Device-Id": "my-device",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (res.ok) return data.results;

  const retryable = [500, 503].includes(res.status) && data.code !== "INVALID_JID";
  if (retryable && attempt < 4) {
    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
    return gowa(path, body, attempt + 1);
  }
  throw Object.assign(new Error(data.message || res.statusText), { code: data.code, status: res.status });
}
```

## Hata ayıklama

* Ayrıntılı günlükler için `APP_DEBUG=true` ile çalıştırın.
* Cihazı kontrol edin: `GET /devices/{device_id}/status` (`is_connected`, `is_logged_in`).
* `GET /health` yalnızca süreç ve veritabanının çalıştığını doğrular; WhatsApp bağlantısını denetlemez.


## Related topics

- [Medya İşleme](https://gowa-docs.mintlify.site/tr/examples/media-handling.md)
- [Hatalar](https://gowa-docs.mintlify.site/tr/api-reference/errors.md)
- [API Referansı](https://gowa-docs.mintlify.site/tr/api-reference/introduction.md)
- [Çoklu Cihaz ve Cihaz Seçimi](https://gowa-docs.mintlify.site/tr/concepts/multidevice.md)
- [Kullanıcı profil resmi](https://gowa-docs.mintlify.site/tr/api-reference/user/kullanıcı-profil-resmi.md)


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