Error codes and client decisions

Interpret HTTP status, machine codes and field details together, and choose safe retry behaviour.

Last updated: 10 November 2026

On this page

Read the error envelope v1 identity, scope and input codes Key and administration codes Licence and installation codes Editing and preview conflicts Output, OGC and webhook codes Other endpoint-specific error codes Result and warning codes separate from HTTP errors WMS XML error codes Validation, network errors and retries

Read the error envelope

v1 errors contain detail, kod and alan. detail may be readable text or an array for request-validation errors. A rejection without a specific machine code returns kod: "hata". Clients should inspect HTTP status first, then kod and alan.

{
  "detail": "İşlem kimliği gerekli.",
  "kod": "alan",
  "alan": "request_id"
}

This example response is used with HTTP 400 when a v1 edit lacks an operation identifier. alan may be null, a field name or an operation position. Do not make automatic decisions based on a particular word in the message.

Cookie-authenticated application errors do not always contain the same additional fields. OGC WMS parameter errors may return XML; authentication errors retain the shared JSON envelope. Check Content-Type before parsing the body.

v1 identity, scope and input codes

`kod`	HTTP	Meaning	Client action
`anahtar`	401	Key is missing, invalid, revoked or unavailable.	Check secure key configuration; do not repeatedly retry the same secret.
`oturum`	401	The required user session is absent.	Renew the relevant session workflow; use Bearer for v1.
`yetki`	403	Current user permissions do not allow the operation.	Check the role and project access.
`kapsam`	403	The key has no write scope.	Create an appropriately scoped key with an authorised user.
`kapsam`	400	The key creation scope is invalid.	Send an array containing `oku`, or `oku` and `yaz`.
`bulunamadi`	404	The record does not exist or is outside access scope.	Refresh the identifier and project scope; do not infer existence.
`alan`	400	A parameter, identifier, bounding box or required operation field is invalid.	Correct the input identified by `alan`.
`modul_kapali`	403	The module requested for reading or writing is disabled.	Check the project's enabled modules.
`modul_yetkisi`	403	Membership has no write permission for the module.	Review project membership with an authorised administrator.
`bolge_disi`	403	The record is outside the writable region.	Match operation scope to the authorised region.
`bolge_kapsam_disi`	403	The operation or record is unsuitable for region-restricted membership.	Use appropriate permissions; geometry is not the only criterion.
`bolge_yok`	403	The region referenced by membership cannot be found.	Correct membership scope.
`sinir`	429	The request counter rejected another request.	Wait for the seconds specified in `Retry-After`.
`hata`	Depends on context	Error without a specific code, including schema rejection, method errors or record conflicts.	Act according to HTTP status and the type of `detail`.

Dedicated operations may use a different rejection status with modul_kapali; the table summarises the shared v1 read/write checks. The endpoint's actual HTTP status takes precedence.

Key and administration codes

`kod`	HTTP	Meaning and action
`kurum_yok`	400	The account has no organisation in which to create keys; check the organisation user.
`anahtar_sinir`	400	The active-key allowance has been reached; review unused keys.
`bitis`	400	The key expiry time is invalid; correct the time zone and future instant.
`kurum_askida`	403	Organisation administration is suspended; notify the authorised organisation administrator.
`uyelik_yetkisi`	403	Managing membership requires project administrator permission.
`erisim_yetkisi`	403	Permission to change the project's access setting is absent.
`surum_cakismasi`	409	The membership version changed; read current membership and reassess.

Licence and installation codes

`kod`	HTTP	Meaning and action
`lisans_salt_okunur`	403	Licence or usage conditions do not permit writes; read licence status.
`lisans_sinif_yok`	403	The operation's installation licence class is unrecognised; notify the installation administrator.
`kontrol_merkezi`	403	The operation belongs to central organisation administration; do not retry with a project API key.
`saat_donem`	503	The operation could not complete because of the clock epoch; inspect system time and installation state.
`bicim`, `alan`, `imza`, `eslesme`	400	Licence file format, fields or verification are invalid; check the file and target installation.
`kurulum`	400	The file or operation does not match this installation.
`cakisma`, `seq`	409	A licence identifier was reused with different content or its sequence is stale; inspect the current record before reapplying.

The same kod can accompany different HTTP statuses in different workflows. For example, an oversized licence envelope may return 413 with bicim, while an unknown installation key may return 404 with anahtar. Do not use kod as a replacement for HTTP status.

Editing and preview conflicts

`kod`	HTTP	Meaning and action
`version`, `surum`	409	The record version changed; reread the record.
`dogrulama_eski`	409	Design validation is stale; validate again.
`cakisma`, `cakisma_yeni`	409	Changes between the design and baseline require resolution.
`ihlal`	409	Publication or connection rules prevent application; correct the report findings.
`fark_bos`	409	There is no design difference to publish; review the scope.
`tasarim_kilitli`, `saha_acik`	403	The design or field state prevents this editing route; return to the appropriate workflow.
`tasarim_durum`	409	The requested design action is incompatible with the current state.

A general v1 /edit version conflict, or reuse of request_id with different ops, may return 409 with hata when no specific code is assigned. Do not assume every conflict uses version. Do not increment a stale version and automatically resubmit the same edit.

Output, OGC and webhook codes

`kod`	HTTP	Meaning and action
`parametre`	400	Output format or selection is invalid; correct the field identified by `alan`.
`cikti_sinir`	400	The output selection exceeds the accepted row or node count; narrow the scope.
`cikti_mesgul`	409	Generation is in progress; retry later.
`cikti_sure`	409	Generation did not finish within its time allowance; narrow the scope.
`cikti_boyut`	409	The file or package size is unsuitable; narrow the scope.
`ogc_kapali`	404	OGC services are disabled in this installation.
`crs_desteklenmiyor`	400	The selected coordinate system is not advertised; use the collection's `crs` list.
`webhook_kapali`	404	Webhook management is disabled in this installation.
`webhook_url`, `webhook_hedef`	400	The target URL format or network-access rule is unsuitable; check `url`.
`webhook_sinir`	400	The active-subscription allowance has been reached; review organisation subscriptions.

Other endpoint-specific error codes

The following index lists additional error codes explicitly defined in source for the documented endpoints. One code may have multiple HTTP statuses. Field shows source field names or Relevant field; — means the field is absent or null. Nested fields and array positions may be determined at runtime.

These codes can also appear in application endpoints; a listed code does not mean that endpoint accepts a v1 key. Check authentication type in the endpoint reference. General exceptions use the shared hata envelope and HTTP status.

Code index: A–D

Code	HTTP	Field	Meaning and client action
`aday`	409	—	Too many circuits are being reassessed in one transaction; divide the operation into meaningful parts.
`alanlar`	400	`alanlar`, `request_id`, `yeniden`	Field selection for applying a measurement is invalid; check submitted fields and the operation identifier.
`ara_uc`	409	—	The cable operation changes an intermediate circuit anchor; review the anchor first.
`aralik`	400	Relevant field	A numeric value or wavelength is outside the permitted range; correct the relevant field.
`arsiv`	409	—	This design or field operation is unavailable in an archived project; check project state.
`asbuilt_acik`	409	—	The work package has an open as-built activity; conclude the existing activity's state.
`ayni_kisi`	403	—	The design submitter cannot approve it; use a different authorised reviewer.
`baglanti`	409	—	The cable end to be moved has existing connections; assess the scope of removing them.
`bagli_degil`	409	—	The technical path cannot be updated; check recorded connections and anchors.
`bbox`	400	`bbox`	The field-package bounding box is invalid; correct its rectangular extent.
`birim`	400	`birim`	The measurement unit does not match the measurement type; distinguish power and loss units.
`bolge_gecersiz`	400	`bolge_ids`	The membership region list is invalid; check project areas and uniqueness.
`bolunemez`	400, 409	`length_m`, Relevant field	The cable value or position is unsuitable for splitting; correct the field and preview again.
`cakisan_bant`	400	Relevant field	Optical-profile wavelength bands overlap; correct the intervals.
`capa_belirsiz`	400	`capa`	The measurement direction does not identify a start anchor; choose an appropriate anchor.
`celisik`	400	`olcum`	The measurement selection conflicts with the separately supplied distance or anchor; separate the inputs.
`crs_uyusmazligi`	400	`file`	File layers have incompatible or unclear coordinate systems; save them in one system or import layers separately.
`cihaz`	403	`cihaz_id`	The field package's device identity does not match; use the correct package and device record.
`cozum_gecersiz`	400	`cozumler`	The design-conflict choice is invalid; save valid choices again.
`dal_dal`	400	—	A new design cannot be opened from an existing design; start from the main project.
`deger`	400	`deger`	The SOR end-to-end loss value is invalid; check the value to apply.
`degistirilemez`	400	`hesap`, `props`	An optical calculation is immutable; use the calculation-creation workflow for current data.
`devre`	400	`devreler`	The circuit selection is invalid; check circuit identifiers in the project.
`dis`	409	—	Moving the equipment affects external connections; review connections first.
`dosya`	400	`dosya`	File metadata is invalid; check record and target details.
`dosya_bos`	400	`dosya`	The uploaded file is empty; select the correct file.
`dosya_boyut`	413	`dosya`	The attachment size is not accepted; prepare a file of an accepted size.
`dosya_bozuk`	409	`dosya`	The file record or content digest does not match; verify existing content and upload again.
`dosya_okunamadi`	400	`file`	The vector file could not be read; check the source file and chosen import format.
`dosya_tur`	400	`dosya`	The file name, type or content validation is unsuitable; prepare a supported file.
`dosya_tutma`	403	`dosya`	Retained measurement files violate installation retention conditions; review storage with the administrator.
`dosya_yok`	404	`dosya`	The measurement or attachment file was not found; check its record and storage location.
`dugum_yok`	404	`dugum`	The output node was not found in the project; refresh node scope.
`durum`	400	`durum`	The filter or record-state choice is invalid; use the endpoint's accepted states.

Code index: E–K

Code	HTTP	Field	Meaning and client action
`eksik`	400	Relevant field	Required companion optical-profile fields are missing; complete the field group.
`erisim_gecersiz`	400	`erisim`	The project access setting is invalid; select organisation or membership access.
`eslem_yok`	409	`esleme`, `fiber_item.props`, Relevant field	A design record reference cannot map to the main project; correct references in the difference report.
`f1_tahmin`	409	—	The cable operation makes the length estimate unreadable; correct length, slack and vertical values.
`fark`	409	—	Cable or circuit values do not match; inspect differences and reassess the operation.
`fiyat`	400	Relevant field	A unit price is not a valid finite number; correct the price and decimal value.
`format_desteklenmiyor`	400	`file`	The file format or required reader is unavailable in this installation; prepare a documented import format.
`gecersiz`	409	Relevant field	A numeric field on the record to split is unreadable; correct it or clear it appropriately.
`gelecek`	400	Relevant field	The measurement date is in the future; check the source date and time zone.
`geometri`	400	—	The line or point geometry is unsuitable for the operation; correct it.
`govde`	400	`format`, `govde`	The body or output format is invalid; use the endpoint's object structure.
`gun`	400	`kod`	The emergency licence code's day value does not match its code type; verify it with the authorised issuer.
`guzergah`	409	—	The cable operation would make the route inconsistent; check segment order and duplicates.
`hedef`	400	`hedef`, `hedef.cable`, `hedef.devre`, `hedef.end`, `hedef.eq`, `hedef.n`, `hedef.side`	Measurement target type, record identifier or endpoint information is invalid; reread the target.
`hedef_yok`	400, 404	`hedef`, `id`	The attachment or its target record cannot be found; check the target within the project.
`hesap`	400, 409	`type`	An optical calculation cannot be created this way or is incompatible with the operation; check the calculation workflow.
`hesap_bag`	400	`hesap_id`	The measurement is outside the selected calculation's circuit or port scope; match the target and calculation.
`ior`	400	`ior`	The group refractive index is invalid; check the measurement value and accepted range.
`is_paketi_durum`	409	—	The work-package state does not permit the action; check the state workflow.
`istek_kimligi`	409	`request_id`	The field-operation identifier differs from the earlier record; review the saved result for the same work.
`iz`	409	—	The cable operation makes trace length unreadable; correct length and slack inputs.
`kablo_uclari`	400	`kablo_uclari`	The server records cable endpoints at measurement time; do not change them from the client.
`kalem`	400	`kalemler`	Unit-price items are missing or invalid; send the complete item table.
`kapsam_gecersiz`	400	`kapsam`	Work-package scope is invalid; correct the scope records and list format.
`kaynak_ad`	400	`ad`	The data-source name is empty, invalid or in use; choose a suitable name.
`kaynak_kullanimda`	409	`kaynak`	The source has an unpublished import; review the existing design's outcome.
`kaynak_yok`	404	`kaynak`	The data source was not found; refresh the source list.
`kesik`	409	—	The cable's cut-fiber record is incompatible with the operation; review fiber continuity and cut states.
`kopuk`	409	—	The selected circuit path cannot be traversed in the topology; correct the path or recorded connections.
`kopya`	400	`kopya`	A library copy is accepted only when creating a new profile; remove it from updates.
`korunamaz`	409	`length_m`, `paylar`, `slack_m`	Splitting cannot preserve existing length or slack information; correct fields in preview.
`kota`	400	`acil_azami`	The licence's emergency extension entitlement is unavailable; review licence status.
`kullanici_yok`	404	`user_id`	The membership user was not found; refresh the organisation user list.
`kullanildi`	400	`seq`	The emergency code has been used or a newer operation exists; check the current licence sequence.
`kullanim_bicim`	400	`kablo/cihaz`	The cable or equipment usage query is invalid; correct query objects.

Code index: L–P

Code	HTTP	Field	Meaning and client action
`lif_bantlar`	400	Relevant field	The cable optical profile lacks the required fiber-band table; choose an appropriate profile.
`lif_olcum`	409	`olcum`	The operation changes the physical scope of a fiber measurement; review its target first.
`lisans`	400	`license_id`	No active licence exists or it does not match this emergency code; check the licence identifier.
`mac`	400	`kod`	Emergency-code verification is invalid for this licence, installation or date; check the correct installation code.
`mesgul`	503	—	The server cannot start the operation now; wait for `Retry-After` and verify the write outcome.
`metin`	400	Relevant field	The text field's type or length is invalid; correct the relevant field.
`metraj`	409	`length`, `lifler.L_m`	The quantity calculation produces an unreadable length; correct geometry, slack and profile values.
`min_max`	400	Relevant field	The order or relationship of minimum and maximum values is invalid; correct the range.
`modul_gecersiz`	400	`moduller`	The membership module list is invalid; send enabled, distinct modules.
`negatif`	409	`slack_m`, `vertical_m`	Slack or vertical length is negative for cable joining; correct source values or clear them appropriately.
`nitelik`	400	`kayip_niteligi`, `nitelik`	Optical-profile or loss-quality selection is invalid; use a permitted choice for the field.
`nm`	400	`nm`	The wavelength is invalid; use an integer within the measurement range.
`not_gerekli`	400	`notu`	The decision or rejection reason is missing; complete the explanation.
`olay`	400	`olay`	No SOR event number is selected or the event distance is unreadable; check the event list.
`olcum`	404	`olcum`	The measurement or linked circuit was not found; reread the measurement target.
`optik`	409	—	The operation violates optical-record integrity; inspect calculation and profile references.
`optik_secim`	409	—	The project already has an optical-profile selection; read and edit it before creating another record.
`paket`	400	`paket`	The project-bundle structure is invalid; check the file and empty-target-project requirement.
`paket_acik`	409	—	This device has an open field package for the project; check the existing package state.
`paket_buyuk`	413	`bbox`	The number of records in the field area is not accepted; reduce the working area.
`paket_durum`	409	—	The package state prevents this operation; check closure and review order.
`paket_sayi`	400	Relevant field	A numeric value in the project bundle is unreadable; correct the source record.
`paket_sinir`	400	—	The active field-package count has reached the installation allowance; review existing packages.
`paket_sure`	409	`sure`	The project-bundle operation did not finish within its time allowance; narrow the scope.
`para`	400	`para`	The currency code is invalid; send a valid three-letter code.
`pay_dugum`	400	`paylar`	The located-slack node list is invalid or contains duplicates; correct linked nodes.
`pay_toplami`	409	`paylar`	Located slack does not sum to the cable's total slack; correct the values together.
`politika`	409	—	The operation is rejected by project policy; review the violation report.
`politika_bayt`	409	—	The policy record size is not accepted; review baselines and exceptions.
`politika_bicim`	409	—	The bundle's fiber policy cannot be read; correct the source policy record.
`politika_sinir`	409	—	Policy baseline or exception scope is not accepted; reduce violations and exceptions.
`proje_buyuk`	409, 413	—	Project scope is not accepted for the design or field workflow; narrow the scope.

Code index: R–T

Code	HTTP	Field	Meaning and client action
`ref`	400	`kopya`, Relevant field	The optical-profile reference is absent or has the wrong type; use an existing profile identifier.
`referans`	400	`referans`	The optical measurement reference method is invalid; choose a method accepted by that type.
`rezerv`	409	—	Cable fiber reservations differ; inspect records and correct reservation decisions.
`risk_bicim`	400	`d`	Circuit selection for the shared-risk query is invalid; correct the identifier list.
`rol_tavan`	400	`rol`	The project role exceeds what the organisation role permits; choose an appropriate membership role.
`saat_araligi`	400	`sistem_saati_araligi`	System time is outside the correction file's interval; check the clock and file.
`sablon`	409	—	Allocation templates differ between cables to be joined; inspect fiber assignments.
`saha_yetki`	403	—	The field-package operation is unauthorised; check package ownership and administrator scope.
`sayfa`	400	`limit`	The page size is invalid; correct the endpoint's pagination field.
`sayi`	400	`quality.accuracy_m`, Relevant field	The numeric field type is invalid; send a number rather than a string or Boolean.
`secili_capa`	400	`yol_sec`, `yollar`	Changing circuit anchors requires selecting the primary path again; review anchors and path selection together.
`secili_yenile`	400	`yol`	This refresh workflow cannot change the selected path; use rerouting.
`sinif`	409	—	Class exceptions differ between fibers to be joined; correct the class decision.
`sonlu`	400	Relevant field	The number is non-finite or unreadable; correct it.
`sonlu_degil`	409	Relevant field	The operation does not produce a readable finite number; check calculation inputs.
`sor`	400	`sor`	The server creates the SOR summary; do not alter it from the client.
`sor_yok`	400	`olcum`, `sor`	No parsed SOR summary exists; check file availability and parsing state separately.
`sure`	409	`sure`	The source-difference operation did not finish within its time allowance; narrow the scope.
`tarih`	400	Relevant field	The measurement date format is invalid; correct the date field.
`tasarim_acik`	409	—	The main project cannot be archived or deleted this way while a design is active; review design state.
`tasarim_ayar`	400	`settings.tasarim`	The design approval setting is invalid; use the defined settings field.
`tasarim_dal`	400	—	This project setting cannot be changed within a design; use administration in the main project.
`tasarim_gecersiz`	400	`tasarim_id`	The source design to link to the work package is invalid; check its identifier.
`tasarim_sinir`	400	—	The active-design count is not accepted; review existing designs.
`tasarim_yetki`	403	—	The design or work-package operation is unauthorised; check the project administration role.
`tasarim_yetkisi`	403	`settings.tasarim`	Permission to change design approval settings is absent; contact the organisation administrator.
`tek_tarafli`	409	Relevant field	The same length field is not present on both cables to be joined; make the values consistent.
`toplam`	409	Relevant field	The joined cable's total value is unreadable; correct source cable values.
`toplu_sinir`	400	`devreler`	The batch circuit selection is not accepted; reduce the circuit scope.
`tur`	400	`tur`, `type`, Relevant field	The optical record or profile type is invalid; choose the expected type.

Code index: U–Z

Code	HTTP	Field	Meaning and client action
`ucuca_yok`	400	`deger`	The SOR file has no end-to-end loss; do not apply an absent measurement value.
`uyelik_gereksiz`	400	`user_id`	An organisation administrator does not need separate project membership; check the role.
`uyelik_yok`	404	`user_id`	The membership record was not found; read current project members.
`uyumsuz`	409	Relevant field	Joining cables changes fiber assignments; correct incompatible attributes.
`x_baglanti`	409	—	Connections at the joining node do not match the expected pairing; inspect the splice diagram.
`yedek_sinir`	400	`sira`, `yollar`	The backup-path count or order is invalid; correct the backup-path list.
`yedek_var`	400	`yol_secim`	Existing backup paths must be assessed before changing the selection; check dependent paths.
`yeterlilik`	400	Relevant field	Optical-profile values do not meet receiver conditions; correct transmitter, receiver and loss ranges together.
`yok`	404	Relevant field	The cable or equipment was not found; check the relevant project identifier.
`yol_bicim`	400	`ad`, `kisit`, `sira`, `yol_ara`, `yol_sec`, `yol_secim`, `yollar`	The primary or backup path selection format is invalid; correct path fields.
`yol_gecersiz`	409	—	The selected path cannot be traversed in the recorded topology; correct the connection chain.
`yol_islem`	400	`entity`, `yol`, `yol_sec`	The same request contains incompatible path operations; send one path-selection intent.
`yol_uzun`	409	—	The circuit path's element scope is not accepted; review the technical path design.
`yon`	400	`yon`	The measurement direction is invalid; use a direction accepted by that measurement type.
`zincir`	409	—	The cables are not connected end-to-end in the same direction; check endpoints and drawing directions.

Result and warning codes separate from HTTP errors

The following values do not replace an HTTP error status. They may appear in parsing states, calculation results or warning lists within successful responses. Check the outer HTTP status separately; these rows do not define a fixed HTTP error status.

Code	Location	Meaning and client action
`kapali`	`sor_durum.kod`	SOR parsing is disabled in this installation; saving the file does not establish successful parsing.
`sor_bicim`	`sor_durum.kod`	The SOR header, block structure or numeric field could not be read; validate the source file again.
`sor_blok_eksik`	`sor_durum.kod`	A required parsing block is absent; obtain the complete file from the measurement instrument.
`sor_ior`	`sor_durum.kod`	The group refractive index is invalid; check the index in the measurement file.
`sor_sinir`	`sor_durum.kod`	The file or parsed content exceeds accepted scope; prepare an appropriate measurement file.
`sor_sure`	`sor_durum.kod`	Parsing did not finish within its time allowance; inspect the file and parsing state.
`sor_surum`	`sor_durum.kod`	The SOR version is unsupported; use a supported measurement-file format.
`okunamaz`	Optical calculation result `kod`	The calculation, fiber loss or measurement value cannot be evaluated; correct the reported cause and source values.
`sonlu_degil`	Optical calculation result `kod`, `alan`	The calculation cannot be represented as a finite number; inspect its inputs. The same code may also appear in HTTP rejections as described above.
`segment_okunamadi`	Route `uyarilar[].kod`	Segment endpoint or length information is unreadable; correct segment data.
`turetilmis_boy`	Route `uyarilar[].kod`	Segment length was derived by splitting; do not treat it as an independent field measurement.
`zemin_yok`	Segment `uyarilar[].kod`	The ground definition was not found; complete the ground information required for the decision.
`buyuk_sayi`	Output `uyarilar[].kod`, `alan`	A large output number is preserved as text; assess it before automatically converting the cell to a number.
`raf`	Output `uyarilar[].kod`, `alan`	Rack placement has a conflict or exceeds its height; inspect the relevant cabinet record.

WMS XML error codes

WMS parameter errors use the code attribute of XML ServiceException instead of JSON kod. Authentication and shared access errors use the JSON envelope.

XML code	HTTP	Field	Client action
`InvalidParameterValue`	400	Relevant WMS request parameter	Check the parameter name, format, coordinates and advertised values.
`LayerNotDefined`	400	`LAYERS`	Check the layer name and key project scope; read the current capabilities document.

Validation, network errors and retries

If a request body, path or query does not match its model, read the detail array in the 422 response. It contains fields such as loc, msg and type. Resending the same body does not fix 400 or 422. Review authentication/permissions for 401 and 403, and scope for 404. An unfamiliar code does not make an HTTP error successful.

Do not guess a request threshold after 429; read the wait in Retry-After. This document does not specify a numeric request threshold. Do not count 503 as a successful write; review any retry header and environment state.

Receiving no HTTP response after a network interruption does not prove that a write failed. For general editing, verify the outcome using the same request_id and ops. Blindly retrying with a new operation identifier can create a duplicate record. This retry rule does not apply to every upload or dedicated POST endpoint.

This glossary covers shared integration rejections and source-defined decision codes for documented workflows. General exceptions with runtime-generated text or codes do not add a dedicated fixed code; v1 returns them in the hata envelope. Continue to use the actual HTTP status when the installation version changes. Read alongside Contract rules, Concurrency and the API reference.