მოთხოვნების ლიმიტები, იდემპოტენტურობა და შეცდომები

მოთხოვნების ლიმიტები

თითოეულ გასაღებს რესურსების ენდპოინტებზე წუთში 300 მოთხოვნის გაგზავნა შეუძლია, ტოკენის ენდპოინტზე კი — 60. ლიმიტები თითო სერვერის ეგზემპლარზე ითვლება, ამიტომ ისინი ზუსტად კი არა, მიახლოებით მიიღეთ. ყოველ პასუხს თან ახლავს მიმდინარე მდგომარეობა:

RateLimit-Policy: apikey;q=300;w=60
RateLimit: limit=300, remaining=298, reset=60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 60

ლიმიტის გადაჭარბებისას იღებთ 429-ს Retry-After: 60 ჰედერით. დაელოდეთ ამდენ ხანს და შემდეგ განაგრძეთ; მჭიდრო ციკლში ხელახლა არ სცადოთ. დროის აღრიცხვის მოწყობილობა, რომელიც ჩანაწერებს მათი მოხდენისთანავე აგზავნის, ან ღამის სინქრონიზაცია ამ რიცხვებს ვერასდროს მიუახლოვდება, საცნობაროს ძირითადი ინფორმაციის პანელი კი თქვენი ბოლო მოთხოვნის დარჩენილ ლიმიტს აჩვენებს.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

იდემპოტენტურობა

ქსელი პასუხებს კარგავს. იმისთვის, რომ ჩაწერის გამეორება უსაფრთხო იყოს, POST /time-clock/events და POST /time-entries მოთხოვნებს დაურთეთ Idempotency-Key ჰედერი — ნებისმიერი უნიკალური სტრიქონი 128 სიმბოლომდე (იდეალურია UUID).

• გასაღებით პირველი მოთხოვნა ჩვეულებრივ სრულდება და მისი შედეგი 24 საათის განმავლობაში ინახება, 4xx შეცდომის ჩათვლით.
• იმავე გასაღებითა და იმავე შიგთავსით გამეორება შენახულ სტატუსსა და შიგთავსს უცვლელად აბრუნებს Idempotent-Replayed: true ჰედერით. არაფერი ორჯერ არ სრულდება.
• იგივე გასაღები სხვა შიგთავსით უარიყოფა 422 idempotency_key_reused კოდით.
• გამეორება, რომელიც პირველი მოთხოვნის დამუშავებისას მოდის, იღებს 409 idempotency_in_flight პასუხს; ცოტა დაელოდეთ და სცადეთ ხელახლა.
• გასაღებები თქვენს კომპანიასა და თქვენს API გასაღებზეა მიბმული, ამიტომ ორი ინტეგრაცია ერთმანეთს ვერ დაემთხვევა.

HTTP/1.1 201 Created
Idempotent-Replayed: true

ჰედერის გარეშეც არსებობს დამცავი მექანიზმი: იმავე თანამშრომლის ჩანაწერი, იმავე გასაღებიდან, იდენტური ჩანაწერიდან 60 წამის განმავლობაში დუბლიკატად ითვლება და მეორის შექმნის ნაცვლად არსებულ ჩანაწერს 200 კოდით აბრუნებს. ეს მოწყობილობაზე ორმაგ დაჭერას ფარავს. ყველაფრისთვის, რასაც პროგრამულად იმეორებთ, ჰედერი გააგზავნეთ.

საცდელი გაშვება

ნებისმიერ ჩაწერას დაურთეთ X-HourSquare-Dry-Run: true და სერვერი ყველა შემოწმებასა და გადაწყვეტას შეასრულებს, არაფერს ჩაწერს და 200-ს დააბრუნებს "dryRun": true მნიშვნელობით. გამოიყენეთ ბარათების მიბმის შესამოწმებლად, შეცდომების დამუშავების გასატესტად ან იმის სანახავად, სად მოხვდებოდა ჩანაწერი, სანამ რეალურად ჩართავთ. ჰედერის არარსებობა რეალურ ჩაწერას ნიშნავს. ინტერაქტიული საცნობარო ამ ჰედერს ნაგულისხმევად აგზავნის, ამიტომ იქ დაჭერა მონაცემებს არასდროს ცვლის, სანამ თავად არ გამორთავთ.

curl -s -X POST https://api.hoursquare.com/api/public/v1/time-clock/events \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-HourSquare-Dry-Run: true' \
  -d '{"employee":{"externalId":"B-1042"},"type":"clock_in","occurredAt":"2026-09-14T08:59:12+02:00"}'

შეცდომები

შეცდომები RFC 9457 სტანდარტს მიჰყვება და application/problem+json ტიპით ბრუნდება:

{
  "type": "https://hoursquare.com/problems/already-clocked-in",
  "title": "Already clocked in",
  "status": 409,
  "detail": "Employee B-1042 is already clocked in since 2026-09-14 08:59. Send clock_out first.",
  "instance": "/api/public/v1/time-clock/events",
  "code": 2904,
  "error": "already_clocked_in",
  "correlationId": "0HN7PQ4K2M3VL:00000007"
}

{
  "type": "https://hoursquare.com/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/api/public/v1/time-clock/events",
  "code": 1800,
  "error": "validation_failed",
  "correlationId": "0HN7PQ4K2M3VL:00000009",
  "errors": [
    { "field": "occurredAt", "message": "Must be an RFC 3339 timestamp with a UTC offset." }
  ]
}

ავთენტიფიკაციის შეცდომებს იგივე ფორმა აქვს: 401 invalid_token (WWW-Authenticate: Bearer ჰედერით), როცა ტოკენი აკლია, ვადაგასულია ან არასწორია, და 403 insufficient_scope, როცა მას წვდომის არე აკლია. ზოგადი წესი: 404 — ვერ მოიძებნა, 409 — მიმდინარე მდგომარეობასთან კონფლიქტი, 422 — არასწორი შეყვანა, 403 — არ არის დაშვებული, 429 — ლიმიტი გადაჭარბებულია, 500 — ჩვენი ბრალია.

გვერდებად დაყოფა

სიები კურსორზეა დაფუძნებული. მოითხოვეთ მაქსიმუმ limit ჩანაწერი (1-დან 100-მდე, ნაგულისხმევად 25); პასუხს აქვს items, hasMore და nextCursor. შემდეგი გვერდის მისაღებად nextCursor უკან cursor პარამეტრად გადაეცით. კურსორები გაუმჭვირვალე სტრიქონებია: არ გააანალიზოთ და არ ააწყოთ ისინი, და არ ელოდოთ ოფსეტებს.

curl -s "https://api.hoursquare.com/api/public/v1/employees?limit=100" \
  -H "Authorization: Bearer $TOKEN"
# → { "items": [ … 100 … ], "nextCursor": "MDFKN1Q4…", "hasMore": true }

curl -s "https://api.hoursquare.com/api/public/v1/employees?limit=100&cursor=MDFKN1Q4…" \
  -H "Authorization: Bearer $TOKEN"
# → { "items": [ … 37 … ], "nextCursor": null, "hasMore": false }

ვერსიები და მოძველება

ძირითადი ვერსია გზაშია: /api/public/v1. v1-ის ფარგლებში მხოლოდ დამატებით ცვლილებებს ვაკეთებთ: ახალი არასავალდებულო ველები, ახალი ენდპოინტები, ახალი ჩამონათვალის მნიშვნელობები (დოკუმენტირებული როგორც „შეიძლება გაიზარდოს“). დაწერეთ კლიენტი ისე, რომ უცნობ ველებს უგულებელყოფდეს და ახალ მნიშვნელობებს უძლებდეს.

თავსებადობის დამრღვევი ცვლილება /v2-ს ნიშნავს. როცა ეს მოხდება, v1 მუშაობას განაგრძობს და გამორთვამდე მინიმუმ ექვსი თვის განმავლობაში Deprecation და Sunset ჰედერებით პასუხობს, ცვლილება კი ამ გვერდზე ცხადდება.

Deprecation: true
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://hoursquare.com/developers/reliability>; rel="deprecation"