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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Whop Entegrasyonlarında Sorun Giderme

> Başarısız API isteklerinden eksik webhook'lara kadar bir Whop entegrasyonundaki yaygın hataları teşhis edin ve düzeltin.

Bir şey bozulduğunda neyin başarısız olduğunu belirleyin, doğru ortama istek gönderdiğinizi kontrol edin ve hata yanıtına bakın. Çoğu sorun şunlardan birine dayanır: yanlış kimlik bilgisi, sandbox/production uyuşmazlığı, eksik izin veya doğru yanıt vermeyen bir webhook işleyicisi.

## Hızlı ön değerlendirme

| Belirti | İlk kontrol | Daha derine inin |
| - | - | - |
| API çağrıları `4xx` veya `5xx` döndürüyor | Durum kodunu, yanıt gövdesini, uç noktayı ve ortamı kontrol edin. | [API isteği hataları](#api-request-errors) |
| API çağrıları `401` döndürüyor | API anahtarının sunucuda bulunduğunu ve API temel URL'si ile aynı ortama ait olduğunu doğrulayın. | [API kimlik doğrulaması](#api-authentication) |
| API çağrıları `403` döndürüyor | Uygulamanın, kullanıcının veya hesabın kaynak için gerekli izne sahip olduğunu kontrol edin. | [İzinler ve kapsamlar](#permissions-and-scopes) |
| OAuth `error` ile geri yönlendiriyor | Geri çağırma URL'sinden `error` ve `error_description` değerlerini okuyun. | [OAuth hataları](#oauth-errors) |
| Checkout öğesi yüklenemiyor veya ödeme başarısız oluyor | `onError` ekleyin, ilettiğiniz varyantı veya ödeme yapılandırmasını inceleyin ve alıcının öğe içinde yeniden denemesine izin verin. | [Ödeme hataları](#checkout-errors) |
| Webhook'lar gelmiyor veya sürekli yeniden deneniyor | Uç noktanın herkese açık olduğunu, uzun süren işlerden önce hızlıca `2xx` döndürdüğünü ve imza doğrulaması için ham istek gövdesini kullandığını doğrulayın. | [Webhook teslimatı](#webhook-delivery) |
| Bir Whop Element `onError` bildiriyor | `message` ve `code` değerlerini günlüğe kaydedin, ardından erişim belirtecini ve ilettiğiniz seçenekleri doğrulayın. | [Öğe hataları](#element-errors) |

## API isteği hataları

Whop standart HTTP durum kodları döndürür. Bir istek başarısız olduğunda yanıt gövdesi nedenini söyler.

Çoğu hata bir kod ve bir mesaj içerir:

```json theme={null}
{
	"error": {
		"code": "invalid_request",
		"message": "Missing required parameter: account_id"
	}
}
```

Bazı OAuth uç noktaları bunun yerine OAuth standardındaki `error` ve `error_description` alanlarını döndürür. Bu durumlar için [OAuth hataları](#oauth-errors) bölümüne bakın.

| Durum | Anlamı | Ne yapmalı |
| - | - | - |
| `400` | İsteğin yapısı geçersiz veya gerekli bir alan eksik. | Gerekli parametreleri, enum değerlerini, kimlikleri ve iç içe nesne yapısını kontrol edin. |
| `401` | İstekte geçerli kimlik doğrulaması eksik. | API anahtarının veya erişim belirtecinin mevcut, geçerli olduğunu ve sunucunuzdan gönderildiğini doğrulayın. |
| `403` | Kimlik bilgisi geçerli ancak işlemi gerçekleştiremiyor. | Uygulama izinlerini, OAuth kapsamlarını, hesap sahipliğini ve alt hesap bağlamını kontrol edin. |
| `404` | Kaynak veya uç nokta bulunamadı. | Rotayı, API sürümünü ve `biz_`, `plan_`, `mem_` veya `user_` gibi Whop etiket kimliğini doğrulayın. |
| `409` | İstek, kaynağın mevcut durumuyla çakışıyor. | Kaynağın en son durumunu getirin ve yalnızca işlem hâlâ geçerliyse yeniden deneyin. |
| `422` | İstek geçerli bir JSON ancak doğrulamadan geçemiyor. | Kullanıcının girdisini düzeltebilmesi için doğrulama mesajını ona gösterin. |
| `429` | İstemci kısa bir süre içinde çok fazla istek gönderdi. | `/api/v1` istekleri için Whop, kimliği doğrulanmış API çağrılarını işlem ve API kimlik bilgisi başına dakikada 600 istekle sınırlar. Hata mesajındaki yeniden deneme süresi geçene kadar bekleyin. |
| `5xx` | Whop isteği tamamlayamadı. | İdempotent işlemler için geri çekilme ile yeniden deneyin, sorun devam ederse destekle iletişime geçin. |

### Hız sınırları

`/api/v1` istekleri için Whop, istek hacmini API işlemi ve API kimlik bilgisi başına izler. Varsayılan sınır dakikada 600 istektir.

Sınırı aştığınızda API şu içerikle `429` döndürür:

```json theme={null}
{
	"error": {
		"type": "rate_limit_exceeded",
		"message": "Try again in 12 seconds."
	}
}
```

Yeniden denemeden önce mesajdaki süre kadar bekleyin. İdempotent istekler için üstel geri çekilme ile yeniden deneyin. Doğrulama, kimlik doğrulama veya izin hatalarını isteği değiştirmeden yeniden denemeyin.

## API kimlik doğrulaması

Kodun çalıştığı yere uyan kimlik bilgisini kullanın.

| Kimlik bilgisi | Ne zaman kullanılır | Yaygın hata |
| - | - | - |
| Account API key | Sunucunuz kendi hesabınız adına işlem yapıyor. | Anahtarı tarayıcı, mobil veya herkese açık istemci koduna koymak. |
| App API key | Uygulama sunucunuz, uygulamanızı yüklemiş hesaplar adına işlem yapıyor. | Uygulamayı yüklememiş veya yetkilendirmemiş bir hesap için uç noktaları çağırmak. |
| Hesap kapsamlı kullanıcı belirteci | Ürününüzün kendi kullanıcıları Whop'a Whop oturumu açmadan erişiyor. | `scoped_actions` değerini atlamak; bu durumda belirteç, onu oluşturan API anahtarının tüm izinlerini devralır. |
| Hesap erişim belirteci | Bir istemcinin, bağlı bir kullanıcı olmadan hesabınıza kısa süreli erişime ihtiyacı var. | Bir kullanıcı olarak işlem yapan ve bu belirteci reddeden uç noktaları çağırmak. |
| OAuth erişim belirteci | Oturum açmış bir kullanıcı, uygulamanıza kendi hesabına erişim veriyor. | Kullanıcı kapsamlı bir belirteci hesap genelinde bir API anahtarı gibi kullanmak. |
| iframe kullanıcı belirteci | Bir Whop uygulaması, bir iframe isteği içinde kullanıcıyı doğruluyor. | İmza doğrulamasını atlamak veya belirteci ilgisiz istemcilere iletmek. |

Bir API isteği başarısız olursa:

1. Ortamın anahtarla eşleştiğini doğrulayın: production anahtarları için SDK'nın `Production` ortamı (varsayılan), sandbox anahtarları için `Sandbox`; API'yi doğrudan çağırıyorsanız `https://api.whop.com/api/v1` ve `https://sandbox-api.whop.com/api/v1`.
2. Kimliklerin dahili sayısal kimlikler değil, `biz_`, `user_`, `mem_`, `plan_`, `prod_`, `app_`, `pay_` veya `ch_` gibi Whop etiket önekleri kullandığını doğrulayın.
3. HTTP durumunu, yanıt gövdesini, uç noktayı ve Whop döndürüyorsa istek kimliğini günlüğe kaydedin.
4. Yalnızca hata geçiciyse veya hız sınırına takıldıysa yeniden deneyin. `401`, `403` veya doğrulama hatalarını isteği değiştirmeden yeniden denemeyin.

> [!WARNING]
>
> Account API anahtarlarını veya App API anahtarlarını asla istemci tarafı kodda açığa çıkarmayın. Tarayıcı, mobil ve iframe kodu sunucunuzu çağırmalı, sunucunuz da Whop'u çağırmalıdır.

## İzinler ve kapsamlar

`403` ve `insufficient_scope` hataları genellikle kimlik bilgisinin geçerli olduğu ancak o işlemi gerçekleştiremediği anlamına gelir.

* Whop uygulamaları için uygulamanın gerekli izinleri [İzinler](https://docs.whop.com/tr/developer/guides/permissions.md) bölümünde istediğini doğrulayın, ardından uygulama ayarlarını kaydedin ve gerektiğinde yeniden yükleyin veya yeniden yetkilendirin.
* OAuth için yalnızca özelliğinizin ihtiyaç duyduğu kapsamları isteyin, ardından bu kapsamları ekledikten sonra kullanıcının OAuth akışını tamamladığından emin olun.
* Kontrol panelinde oluşturulan API anahtarları için anahtarın, kimliğini `account_id` olarak ilettiğiniz hesaba ait olduğunu doğrulayın.
* Alt hesaplar için, ileteceğiniz hesabı seçmeden önce işlemin sahibinin üst hesap mı yoksa alt hesap mı olması gerektiğini doğrulayın.

## OAuth hataları

OAuth hataları, `error` ve `error_description` içeren standart bir yük veya yönlendirme sorgu dizesi döndürür.

```json theme={null}
{
	"error": "invalid_grant",
	"error_description": "Authorization code has expired"
}
```

| Hata | Anlamı | Çözüm |
| - | - | - |
| `invalid_request` | Gerekli bir parametre eksik veya hatalı biçimlendirilmiş. | `client_id`, `redirect_uri`, `response_type`, `code_challenge` ve `code_challenge_method` değerlerini kontrol edin. |
| `invalid_grant` | Yetkilendirme kodu, yenileme belirteci veya erişim belirtecinin süresi dolmuş, zaten kullanılmış ya da Whop tarafından iptal edilmiş. | OAuth akışını yeniden başlatın veya kullanıcıdan tekrar oturum açmasını isteyin. Yetkilendirme kodları tek kullanımlıktır. |
| `invalid_client` | Whop uygulama istemcisini tanımıyor. | Doğru uygulamayı ve ortamı kullandığınızı doğrulayın. |
| `invalid_scope` | İstenen kapsam geçerli değil veya tanınmıyor. | Uygulama ayarlarınızdaki mevcut kapsamları kontrol edin ve yazım hatalarını kaldırın. |
| `insufficient_scope` | Belirteç, uç noktanın gerektirdiği kapsamı içermiyor. | Kapsamı uygulama ayarlarınıza ekleyin ve OAuth onayını yeniden çalıştırın. |
| `access_denied` | Kullanıcı veya hesap yetkilendirme isteğini reddetti. | Kullanıcı erişim vermemeyi seçti veya hesap bu uygulamayı kısıtlıyor. |
| `unsupported_response_type` | `response_type` parametresi desteklenmiyor. | Yetkilendirme kodu akışı için `response_type=code` kullanın. |
| `unsupported_grant_type` | `grant_type` parametresi desteklenmiyor. | `authorization_code` veya `refresh_token` kullanın. |
| `rate_limit_exceeded` | OAuth yetkilendirme, belirteç veya inceleme istekleri kısa süreli bir sınıra takıldı. | Geri çekilin ve varsa `Retry-After` başlığına uyun. |

> [!TIP]
>
> Yönlendirme URI'leri tam olarak eşleşmelidir. `https://example.com/oauth/callback` yapılandırdıysanız, `https://example.com/oauth/callback/` farklı bir URI'dir.

## Ödeme hataları

Checkout öğesi ve iOS ödemesi farklı nedenlerle başarısız olabilir. Bunları aynı şekilde ayıklayın: varyantı veya ödeme yapılandırmasını kontrol edin, hata geri çağırmasını inceleyin ve teslimatı sunucunuzda doğrulayın.

### Checkout öğesi

* `onError` ekleyin. Öğe yüklenemediğinde veya çöktüğünde, programatik işleme için bir `message` ve bir `code` ile çalışır.
* Uyumluluk özelliği `plan` değerini iletiyorsanız, varyantın var olduğunu, etkin olduğunu ve beklediğiniz hesaba ait olduğunu doğrulayın.
* `checkoutConfiguration` iletiyorsanız, sunucunuzun onu oluşturduğunu ve `ch_` kimliğini ilettiğinizi doğrulayın.
* Her seçenek oluşturma sırasında ayarlanır. Siparişi değiştirmek için `update()` çağırmak yerine yeni bir ödeme öğesi bağlayın.
* Başarısız bir ödeme, aynı ödeme ekranını nedeni gösterilmiş şekilde yeniden açar; böylece alıcı yeniden bağlama gerekmeden tekrar ödeme yapabilir.
* Başarı ve yeniden deneme durumlarını görüntüleyebilen bir rotada `returnUrl` sağlayın. 3DS veya bir banka sayfası gibi site dışı bir adım alıcıyı oraya geri döndürür.
* Teslimat için webhook'ları kullanın. Yönlendirme arayüz için yararlıdır, ancak sunucunuz `payment.succeeded` olayına güvenmelidir.

### `iOS` ödemesi

Beklenen ve beklenmeyen hataları farklı yollarla işleyin:

```swift theme={null}
do {
    let result = try await checkout.purchase(planId)
    print("Receipt ID: \(result.receiptId)")
} catch WhopCheckoutError.notConfigured {
    // SDK was not set up. Call WhopCheckout.configure() first.
} catch WhopCheckoutError.cancelled {
    // The user dismissed checkout. This is not a payment failure.
} catch WhopCheckoutError.paymentFailed(let message) {
    showError(message)
} catch {
    showError("Something went wrong. Please try again.")
}
```

## Webhook teslimatı

Yaygın webhook sorunları:

* **Hiç olay alınmadı**: webhook URL'sinin herkese açık olarak erişilebilir olduğunu, `https` kullandığını ve doğru hesaba ve ortama ait olduğunu doğrulayın.
* **İmza doğrulaması başarısız oluyor**: ham istek gövdesini `unwrapWebhook` fonksiyonuna iletin. Doğrulamadan önce JSON ayrıştırmayın.
* **Yeniden denemeler devam ediyor**: doğrulamadan sonra, uzun süren işleri bir arka plan işinde başlatmadan önce hızlıca `2xx` yanıtı döndürün.
* **Yinelenen teslimat**: Whop webhook'ları en az bir kez teslim eder. `webhook-id` veya başka bir olay tanımlayıcısını saklayın ve işleyiciyi idempotent hale getirin.
* **Beklenmeyen sıra**: olayların kronolojik sırayla geldiğini varsaymayın. Sıra önemliyse kaynağın mevcut durumunu getirin.

Yerel geliştirme için bir tünel ile herkese açık bir URL'yi makinenize yönlendirin ve bu URL'yi kontrol panelindeki webhook ayarlarında kullanın.

## Öğe hataları

Her [Whop Element](https://docs.whop.com/tr/elements/latest/getting-started.md) bir `onError` geri çağırması kabul eder. Öğe yüklenemediğinde veya çöktüğünde çalışır ve değer bir `message`, programatik işleme için isteğe bağlı bir `code` ve bir host-state kaynağı başarısız olduğunda bir `sourceKey` taşır.

Geliştirme sırasında her zaman ekleyin:

```tsx theme={null}
<CheckoutElement
	onError={(error) => {
		console.error("CheckoutElement failed", error.code, error.message);
	}}
/>
```

Bir öğe yüklenemezse:

1. Erişim belirtecinin beklediğiniz hesap için oluşturulduğunu ve öğenin referans sayfasında listelenen kapsamları taşıdığını doğrulayın.
2. Kendi alan adınızda her zaman bir `accessToken` iletin. Görüntüleyenin oturumu yalnızca whop.com üzerinde çalışır.
3. `mount` çağırmadan önce kapsayıcının var olduğunu doğrulayın. React bileşenleri kendilerini bağlar.
4. Öğenin başlatılıp başlatılmadığını bilmek için `onReady` olayını dinleyin.
5. Öğe kurtarılamaz bir duruma girerse `destroy()` çağırın ve yeni bir tane oluşturun.

[Elements sorun giderme tablosu](https://docs.whop.com/tr/elements/latest/getting-started.md#troubleshooting) yaygın belirtileri ve nedenlerini listeler.

## Sandbox ve production

Sandbox verileri ve production verileri ayrıdır.

| Ortam | Kontrol paneli | API |
| - | - | - |
| Sandbox | `https://sandbox.whop.com` | `https://sandbox-api.whop.com/api/v1` |
| Production | `https://whop.com` | `https://api.whop.com/api/v1` |

Sandbox'tan production'a geçerken:

* Yeni production API anahtarları oluşturun.
* SDK ortamını `Sandbox` yerine `Production` olarak değiştirin veya 1.x sürümündeki `baseUrl` / `base_url` / `WithBaseURL` sandbox geçersiz kılmasını kaldırın.
* Yalnızca sandbox'ta bulunan ürünleri, ödeme bağlantılarını, webhook'ları ve alt hesap kayıtlarını production'da yeniden oluşturun.
* Webhook URL'lerinin yerel bir tünele değil, production altyapısına işaret ettiğini doğrulayın.

## Yardım isterken nelerin ekleneceği

Aşağıdakilerden mümkün olduğunca fazlasını ekleyin:

* Başarısız olan uç nokta, SDK yöntemi veya öğe adı.
* Ortam: sandbox veya production.
* Durum kodu, hata gövdesi, OAuth `error_description` veya öğenin `onError` değeri.
* İlgili Whop kimlikleri, gizli bilgiler çıkarılmış olarak.
* Webhook sorunları için webhook olay kimliği veya `webhook-id` başlığı.
* İstemciyi, ödeme sayfasını, OAuth URL'sini, webhook işleyicisini veya öğeyi nasıl oluşturduğunuzu gösteren kısa bir kod parçacığı.

> [card] [OAuth](https://docs.whop.com/tr/developer/guides/oauth.md)
>
> OAuth 2.1 + PKCE akışını oluşturun ve belirteç yenilemeyi yönetin.

> [card] [Webhook'lar](https://docs.whop.com/tr/developer/guides/webhooks.md)
>
> Olayları işlemeden önce imzaları doğrulayın ve yeniden denemeleri yönetin.

> [card] [İzinler](https://docs.whop.com/tr/developer/guides/permissions.md)
>
> Uygulama izinlerini seçin ve bunları içerik üreticilerine açıklayın.

> [card] [Sandbox'ta test edin](https://docs.whop.com/tr/developer/guides/sandbox.md)
>
> Production'a dokunmadan API çağrılarını ve ödeme akışlarını test edin.


## Related topics

- [Elements ile başlarken](https://docs.whop.com/tr/elements/latest/getting-started.md)
- [GoHighLevel](https://docs.whop.com/tr/third-party-integrations/gohighlevel.md)
- [Sunucu Tarafı Olayları Gönderin](https://docs.whop.com/tr/developer/ads/events-api.md)
