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}
}

HataAyrinti

kodstringrequired
Machine-readable error code (same as hata).
mesajstringrequired
Human-readable message (same as detay).
tarafstringrequired
Where the fault lies: istemci (request, key, plan), ulawk (our side), kaynak (the official source is unreachable right now). Values: istemci, ulawk, kaynak
kaynakstringrequirednullable
Which source, for source-side errors; otherwise null. Values: ttsg, kap, yurt_disi_sicil
tekrar_denenebilirbooleanrequired
Whether the same request may be retried later.
tekrar_snintegerrequirednullable
Suggested wait in seconds. When set, a Retry-After header is sent too.

`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).

Errors

#taraf: whose fault

#Codes

`taraf`: whose fault

Codes