Errors, limits and idempotency

Error format

Errors come back as JSON with a detail field. Most errors are a short machine code:

{"detail": "insufficient_scope"}

For validation errors, detail is a list of fields:

{"detail": [{"type": "missing", "loc": ["body", "items", 0, "urun_adi"], "msg": "Field required"}]}

When a plan limit is exceeded, detail carries a readable message (in Turkish):

{"detail": [{"code": "limit_asildi", "limit": "gunluk_giden_arama", "deger": 200, "message": "…"}]}

Status codes

Code	detail	Meaning
401	api_key_required	No Authorization: Bearer … (response has WWW-Authenticate: Bearer)
401	invalid_api_key	The key is invalid or revoked
403	insufficient_scope	The key lacks the required scope
403	publishable_key_not_allowed	A publishable key can’t be used here
404	not_found	No such record, or the feature is off in your plan
409	idempotency_in_progress	The first request with the same Idempotency-Key is still running
413	payload_too_large	The body is larger than 5 MB
422	duplicate_key: <id>	The same id twice in one request
422	idempotency_key_reused	The same Idempotency-Key was used for a different request
422	invalid_idempotency_key	The key is longer than 255 characters
422	idempotency_key_required	POST /api/v1/aramalar was sent without a key
422	unknown_purpose, invalid_phone, invalid_status, invalid_range, unknown_filter	Endpoint-specific validation
422	limit_asildi (list)	Plan limit
429	rate_limited	Rate limit; wait the number of seconds in Retry-After
5xx	—	Temporary error; retry with the same Idempotency-Key

Rate limit

120 requests per minute per key (fixed window). When exceeded you get 429 rate_limited and a Retry-After header with the seconds left in the window. On the button’s browser endpoints the counter only increases for requests from an allowed domain; failed button attempts are also limited to 20 per minute per IP (429 too_many_failures).

Body limit and batches

• Body up to 5 MB (413 payload_too_large).
• Batch writes take 1–1000 records per request.

Idempotency

If you send an Idempotency-Key header on a write request (POST, PUT, PATCH, DELETE):

• The response is kept for 24 hours. The same key with the same request (method, path, query and body) returns the same response, with an Idempotent-Replayed: true header.
• The same key with a different request returns 422 idempotency_key_reused.
• A second request with the same key while the first is still running gets 409 idempotency_in_progress.
• 5xx responses and 401, 403, 413, 429 are not stored; you can retry with the same key after them.
• The key is scoped to your API key; up to 255 characters.

Tip

For POST /api/v1/aramalar the Idempotency-Key is required: resending the same request with the same key after a network error never calls the customer twice. Derive the key from the job itself (e.g. sikayet-<order no>-<attempt>); don’t generate a random one for every retry.

Pagination

List endpoints use a cursor: send the response’s next_cursor as cursor in the next request. limit is 1–100 (default 50). Requests and calls are incremental (oldest to newest; the cursor is kept on an empty page); carts are sorted newest first.