Service limits

Rate limits, request body caps and pagination bounds.

Rate limit

For authenticated requests, 50 requests per 10 seconds per service group and key. Counting is per group, not per endpoint; the limit is the same on both verticals. Order and store endpoints are in a different group from the catalogue, so a large catalogue upload does not block order acceptance.

Groups and their endpoints

Alan	Tip	Açıklama
`siparis`	group	Reading and writing orders, invoice, courier, disputes, review replies, picking and return, test order. GET /orders · GET /orders/{id} · POST /orders/{id}/status · PUT /orders/{id}/invoice · PUT /orders/{id}/courier · GET /disputes · POST /disputes/{id}/respond · POST /reviews/{id}/reply · POST /orders/test · POST /orders/{id}/picking · POST /orders/{id}/return
`magaza`	group	Business information, status, working hours and webhook settings. GET /merchant · PUT /merchant/status · PUT /merchant/working-hours · GET /webhook · PUT /webhook · DELETE /webhook · POST /webhook/test
`durum`	group	Connection notice. POST /reachability
`konum`	group	The courier's last position. PUT /orders/{id}/courier/location
`katalog-okuma`	group	Menu, category tree, product list, batch results, cancellation reasons and reviews. GET /cancel-reasons · GET /reviews · GET /menu · GET /categories · GET /products · GET /batches/{id}
`katalog-yazma`	group	Menu price and status; product creation, price and stock, sale status. PUT /menu/items/price · PUT /menu/items/status · PUT /menu/categories/status · POST /products · PUT /products/price-and-stock · PUT /products/status

The group of each operation is also written in the x-service-group field of the OpenAPI document. The test-order endpoint (POST /orders/test) additionally has a quota of 20 requests per hour; beyond that it returns 429 with reason: test_order_quota.

The remaining budget is returned in the headers of every response that reaches authentication (including 304 and error responses). On 429, wait for Retry-After and spread requests out.

Response headers

RateLimit-Limit: 50
RateLimit-Remaining: 37
RateLimit-Reset: 6
Retry-After: 6          # only on 429

Authentication failure limit

Failed authentication attempts are counted in a separate bucket: 20 per 60 seconds per IP address. Beyond that the response is 429 too_many_requests with reason: auth_failures. On these responses, and on a 401 unauthorized rejected at authentication, the RateLimit-Limit value is 20.

Alan	Tip	Açıklama
`403 integrator_header_required`	no limit headers	Rejected before authentication; the response carries only the `X-Request-Id` and `X-Api-Environment` headers.
`400 invalid_operator`	no limit headers	Rejected before authentication in the same way.
`401 environment_mismatch`	no limit headers	Rejected before authentication in the same way.
`401 (anahtar değişti)`	RateLimit-Limit: 50	If the key is found to have changed during a write, the 401 carries the group headers and the value is 50.
`500`	no limit headers	If an unexpected error occurs at the authentication stage, the response carries no `RateLimit-*` headers.

Request body caps

Alan	Tip	Açıklama
`All bodies`	1 MB	Beyond this: `413 payload_too_large`.
`PUT /webhook`	16 KB	Beyond this: `413 payload_too_large`.
`PUT /menu/items/price · /menu/items/status · /menu/categories/status`	100	At most 100 items per request; more returns `400 too_many_items`.
`POST /products · PUT /products/price-and-stock · PUT /products/status`	1000	At most 1000 items per request on Çarşı; more returns `400 too_many`, an empty list returns `400 empty`.
`POST /orders/{id}/picking · items`	200	At most 200 item results per request.
`POST /disputes/{id}/respond · items`	200	At most 200 items in an item-level response.
`POST /orders/{id}/picking · receiptUrl`	8 MB	Receipt image; a larger file or a file that is not an image is not stored and the response carries a `receipt_not_saved` warning.

Pagination bounds

Alan	Tip	Açıklama
`GET /orders`	limit ≤ 50	Default 50.
`GET /reviews`	limit ≤ 50	Default 20.
`GET /products`	limit ≤ 500	Default 100.

List endpoints return { items, nextCursor }; pagination is by cursor only. GET /disputes, GET /categories and GET /cancel-reasons are not paged and nextCursor is always null.

Tightening a limit is not a breaking change: client code stays the same, only 429s become more frequent. Increases are announced in the changelog.