Reference

Errors

Errors come back as problem details with a stable code for your program and a plain detail for people. Here is what each code means and what to do.

{
  "type": "https://developer.clocklap.com/errors/entry_locked",
  "title": "Conflict",
  "status": 409,
  "code": "entry_locked",
  "detail": "This pay period is locked. Unlock it before changing its hours.",
  "request_id": "req_4f1c2a9b7d3e5f60"
}

Retrying#

Retry 429 (after RateLimit-Reset), 5xx and network errors, with backoff, and an Idempotency-Key so nothing happens twice.
Don't retry other 4xx unchanged: fix what detail says first.

Codes#

Status	Code	Meaning and what to do
400	`validation_failed`	A field is missing or the wrong shape. `detail` names each one, as `field: problem`.
400	`invalid_reference`	An ID you sent doesn’t exist (for example a `location_id`).
400	`invalid_date` `invalid_range` `range_too_long`	A date or range is wrong or too long. `detail` says the limit.
400	`unknown_scope` `unknown_event_type` `invalid_expand`	A value isn’t one of those allowed.
400	`invalid_url` `insecure_url` `private_url`	A webhook URL must be HTTPS and reach a public address.
401	`unauthorized`	No key, or the key is wrong, revoked or expired.
403	`forbidden`	The key’s scopes don’t allow this, or a person is needed rather than a key.
403	`workspace_suspended`	The workspace is suspended. An owner can resolve it in Billing.
404	`not_found`	Nothing with that ID, or you can’t see it.
409	`conflict`	It already exists (for example an email in use).
409	`overlap` `overlaps`	The shift would overlap another of the same person’s.
409	`entry_locked`	The pay period is locked, so its hours can’t change.
409	`idempotency_key_busy`	The first request with this `Idempotency-Key` is still running. Retry shortly.
409	`idempotency_key_reused`	This `Idempotency-Key` was used for a different request. Use a new one.
421	`wrong_region`	The key belongs to the other region. The body’s `api_url` is the address to use.
400 or 422	`reason_required`	Changes to hours need a `reason`.
400 or 422	`unassigned_location`	The person isn’t assigned to that location. Add them to it first.
429	`rate_limited`	Too many requests. Wait for `RateLimit-Reset` seconds.
500	`internal_error`	Something went wrong on our side. Retry with backoff; if it persists, send us the `request_id`.

Punch errors#

POST /v1/punches answers 422 “Punch not applied” with one of these codes when a punch can't apply:

Code	Meaning
`already_clocked_in`	They’re already clocked in.
`not_clocked_in`	There’s no open shift to clock out of or break in.
`already_on_break`	They’re already on a break.
`not_on_break`	There’s no break to end.
`before_clock_in`	The time is before the shift started.
`future_time`	The time is in the future.
`too_old`	The time is too long ago to record as a punch: add a shift instead.
`overlap`	It would overlap another shift.
`period_locked`	The pay period is locked.
`unassigned_location`	They aren’t assigned to that location.
`method_disabled`	That way of clocking in is turned off for the site.
`gps_required`	The site needs a location with each punch.
`photo_required`	The site needs a photo with each punch.
`mock_location`	The location came from a fake-GPS app.