/
LinkHarbor API hata yanıtları nasıl yapılandırılır, en önemli hata kodları ne anlama gelir ve kodun bunlara nasıl tepki vermeli.
API’nin her hata yanıtı aynı biçime sahiptir. Kodun message içindeki metne değil, error alanındaki hata koduna güvenmeli – kod sabit kalır, metin ise değişebilir ve hesap diline çevrilir.
Bir hata yanıtının yapısı
{
"error": "validation_failed",
"message": "Some of the information provided is invalid. Please check and try again.",
"details": [
{ "field": "title", "reason": "minLength", "message": "…" }
],
"request_id": "6b1f0c2e-…"
}- error
- Makine tarafından okunabilir kod, örneğin not_found. Çoğu hatada X-Error-Code başlığında da bulunur – ama gövdedeki alana güven.
- message
- Hesap dilinde insan tarafından okunabilir açıklama: bir API anahtarıyla çalışma alanı sahibininki, bağlı bir uygulamayla onu bağlayan kişininki. Geçerli bir token olmadan – örneğin token kontrolünden gelen 401 – dil Accept-Language’i izler, aksi halde İngilizcedir. Content-Language başlığı dili belirtir.
- details
- Yalnızca söylenecek daha fazla şey olduğunda bulunur. Girdi doğrulamasından gelen 422 için her sorun için field, reason ve message içeren bir liste; iş mantığından gelen 422 ve diğer tüm hatalar için bir nesne, örneğin reason, retry_after_sec veya bir issues listesiyle. Bir boyut aşıldığında field, reason ve limit, 413 request_too_large için max_bytes ve max_kb içerir. Bu yüzden details’in bir liste olup olmadığını kontrol et.
- request_id
- İsteğin kimliği. X-Request-Id başlığında da bulunur. Destek ekibiyle iletişime geçtiğinde bunu ekle.
İstisnalar: 429 rate_limited yanıtında details yerine retry_after_sec alanı vardır; 429 ve 403 insufficient_scope ile gövdede request_id eksiktir. Token kontrolünden gelen 401 ve şema kontrolünden gelen 422’nin X-Error-Code başlığı yoktur ve şema kontrolünde yalnızca üst düzey message çevrilir; details içindeki metinler İngilizce kalır. X-Request-Id başlığı her zaman ayarlanır.
En önemli kodlar
| HTTP | error | Anlamı | Ne yapmalı |
|---|---|---|---|
| 400 | invalid_json | Gövde geçerli JSON değil | JSON’u kontrol et |
| 400 | bad_request | Yanlış Content-Type veya hatalı istek | Content-Type: application/json ayarla |
| 401 | missing_bearer_token | Authorization başlığında token yok | Authorization: Bearer … başlığını ayarla |
| 401 | invalid_token | Token’ın süresi dolmuş veya geçersiz ya da anahtar silinmiş | Yeni bir token al; işe yaramazsa anahtarı kontrol et |
| 401 | invalid_api_key | Token değişiminde yanlış anahtar kimliği veya gizli değer | Kimlik bilgilerini kontrol et |
| 402 | plan_limit_reached | Plan limitine ulaşıldı, örneğin kısa bağlantılar için | Yükselt veya girişleri sil |
| 403 | insufficient_scope | Kapsam eksik veya uç nokta API anahtarları için etkin değil | Doğru kapsamla bir anahtar oluştur |
| 403 | forbidden | Bu işlem için yetki yok | Panelde yap |
| 403 | feature_not_available | Özellik plana dahil değil | Planı kontrol et |
| 403 | block_type_requires_plan | Blok türü yalnızca daha yüksek bir planda kullanılabilir | Farklı bir blok türü seç veya yükselt |
| 403 | template_locked | Premium şablon mevcut planda kullanılamıyor | GET /v1/templates/available listesinden bir şablon seç |
| 403 | workspace_suspended, workspace_read_only, workspace_grace_expired | Açık bir ödeme nedeniyle çalışma alanı kilitli veya salt okunur | Ödemeyi panelde hallet |
| 404 | not_found | Kaynak yok veya çalışma alanına ait değil | Kimliği kontrol et |
| 409 | conflict | Mevcut durumla genel çakışma | Durumu yeniden yükle, girdiyi değiştir |
| 409 | workspace_template_in_use | Çalışma alanı şablonu hâlâ sayfalar tarafından kullanılıyor; sayı details.count içinde | Sayfaları başka bir şablona geçir, sonra sil |
| 409 | handle_taken, slug_taken | Kullanıcı adı veya kısa bağlantı slug’ı zaten alınmış | Farklı bir değer seç |
| 409 | form_in_use, page_not_private, page_not_published, never_published | Durumla çakışma: form hâlâ bir sayfada, sayfa özel değil veya yayınlanmamış, hiç yayınlanmamış | Durumu değiştir, sonra tekrar dene |
| 409 | page_limit_reached, link_limit_reached, block_limit_reached, form_limit_reached, asset_limit_reached, asset_storage_limit_reached, workspace_template_limit_reached | Planın sayı veya depolama limitine ulaşıldı | Girişleri kaldır veya yükselt |
| 409 | draft_not_publishable | Taslakta sorunlar var; liste details.issues içinde | Sorunları düzelt, sonra yeniden yayınla |
| 413 | request_too_large | Gövde bu uç nokta için izin verilenden büyük (64 KB, 1 MB veya 2 MB); limit details.max_kb içinde | İstek başına daha az veri gönder, bkz. Hız limitleri |
| 413 | payload_too_large | Yüklenen dosya 10 MB’tan büyük | Dosyayı küçült |
| 422 | validation_failed | Geçersiz girdi veya bilinmeyen alan; ayrıntılar details içinde | Alanları details’te anlatıldığı gibi düzelt |
| 422 | handle_reserved, target_url_invalid, target_url_scheme, target_url_host | Kullanıcı adı ayrılmış ya da hedef URL geçersiz veya izin verilmiyor | Farklı bir değer seç |
| 422 | workspace_template_disabled | Seçilen çalışma alanı şablonu devre dışı | Şablonu “Alan adları ve şablonlar” altında etkinleştir ya da başka birini seç |
| 422 | template_css_external, template_section_invalid | Çalışma alanı şablonu: CSS harici sunuculardan yüklüyor ya da bir {{#if}}/{{#unless}}/{{#each}} bölümü yanlış yerleştirilmiş | Harici adresleri kaldır ya da bölümü aynı etiket veya metin içinde kapat |
| 422 | custom_css_external | Özel CSS harici sunuculardan bir şey yüklüyor | Harici adresleri CSS’ten kaldır |
| 429 | rate_limited, api_key_locked | Çok fazla istek ya da hatalı denemelerden sonra anahtar kilitli | Retry-After veya details.retry_after_sec ne diyorsa o kadar bekle |
| 500 | internal_error | Beklenmeyen hata | Daha sonra tekrar dene, request_id’yi not al |
| 503 | service_unavailable | Hizmet geçici olarak kullanılamıyor | Bir aradan sonra tekrar dene |
Girdi hatalarını okuma
422 validation_failed ile details her sorunu ayrı ayrı listeler: field alanın yoludur (iç içe nesneler için eğik çizgilerle, örneğin theme_config/button_style), reason ihlal edilen kuraldır, örneğin required, minLength, maxLength, enum veya additionalProperties. additionalProperties ile mesaj hangi alanların bilinmediğini söyler – çoğu zaman alan adında bir yazım hatası.
Kodunda önerilen ele alış
- 400, 413 ve 422: yeniden deneme, bunun yerine isteği düzelt
- 401 invalid_token: bir kez yeni bir token al ve yeniden dene
- 403: yeniden deneme; kapsamı, planı veya bunu kimin yapmaya yetkili olduğunu kontrol et
- 404: kimliği kontrol et; bir silmeden sonra bu normaldir
- 409: durumu yeniden yükle ve işlemin hâlâ gerekli olup olmadığına karar ver
- 429: Retry-After ne diyorsa o kadar bekle, sonra yeniden dene – bkz. Hız limitleri
- 500 ve 503: artan aralarla birkaç kez yeniden dene
Bunlar da işine yarayabilir
Bir şey bulamadın mı?
Neye ihtiyacın olduğunu bize anlat, destek ekibimiz sana kişisel olarak yardımcı olsun.