# Errors

All endpoints return the same error body. For older clients `hata` (code) and `detay` (message) never change; structured information is in `hata_ayrinti`. Messages are in Turkish.

```json
{
  "hata": "kaynak_erisilemiyor",
  "detay": "Ticaret Sicili Gazetesi şu an yanıt vermiyor; kısa süre sonra yeniden deneyin.",
  "hata_ayrinti": {"kod": "kaynak_erisilemiyor", "mesaj": "…", "taraf": "kaynak", "kaynak": "ttsg",
                   "tekrar_denenebilir": true, "tekrar_sn": 300}
}
```

:::sema HataAyrinti

## `taraf`: whose fault

| `taraf` | Meaning | What to do |
|---|---|---|
| `istemci` | Request, key or plan | Fix the request; retrying will not help (except 429). |
| `ulawk` | Our side | Retry after `tekrar_sn`. |
| `kaynak` | The official source is unreachable | Retry after `tekrar_sn`; see /durum/ for status. |

## Codes

| HTTP | `hata` | When |
|---|---|---|
| 400 | `gecersiz_parametre` · `gecersiz_kategori` · `gecersiz_tarih` · `gecersiz_gun` · `eksik_alan` · `gecersiz_sicil` · `gecersiz_json` · `gecersiz_webhook` | Bad parameter or body |
| 400 | `deneme_desteklenmiyor` | Endpoint not available with a sandbox key |
| 401 | `yetkisiz` | Missing or invalid key |
| 402 | `kota_doldu` | Plan allowance used up |
| 403 | `anahtar_gerekli` | Operation requires an API key (a browser session is not enough) |
| 404 | `bulunamadi` | No such record or no access |
| 404 | `arsivde_yok` | Gazette not archived yet (retryable) |
| 404 | `kap_eslesmesi_yok` | The company is not matched to a KAP member |
| 405 | `yontem` | Wrong HTTP method |
| 429 | `hiz_siniri` | Hourly limit exceeded; Retry-After |
| 500 | `ic_hata` | Unexpected error; retryable |
| 502 | `webhook_teslim_hatasi` | Test notification could not be delivered to your endpoint |
| 503 | `kaynak_erisilemiyor` | The official source is not answering |

> Sanctions screening and the legacy endpoints (`/api/v1/companies`) return a plain body for historical reasons (no `hata_ayrinti`).