Synchronous writes and operations

Writes in Vacation Tracker are processed in the background. API v2 hides that for you in most cases: a write request waits until the main part of the change has been applied, then returns the result.

Synchronous writes

When you create, update, delete, or act on a resource, the API:

1. checks your key's scopes and the X-On-Behalf-Of header,
2. checks the Idempotency-Key, if you sent one,
3. submits the change,
4. waits until the main part of the change reports back,
5. reads the resource back and returns it.

"Main part" means the step that decides whether the change succeeded, for example saving the leave. Follow-up work, such as calendar sync or Slack and email notifications, is not waited for.

The returned resource is read right after the change is applied, so it can be slightly stale. If you need follow-up fields, read the resource again a moment later.

Accepted writes (202)

If the change has not reported back after the wait limit, the API stops waiting and returns 202 Accepted:

{
  "operation": {
    "id": "pa_3f6e2a1c-8b4d-4c1e-9a7f-5d2b0c6e8f91",
    "status": "PENDING",
    "url": "/v2/operations/pa_3f6e2a1c-8b4d-4c1e-9a7f-5d2b0c6e8f91"
  }
}

The wait limit is 20 seconds, counted from when the request arrives. You also get a 202 when the change succeeded but the resource could not be read back yet; in that case status is SUCCEEDED.

A 202 does not mean the change failed. It is still running, and it will finish on its own.

Polling an operation

curl https://api.vacationtracker.io/v2/operations/pa_3f6e2a1c-8b4d-4c1e-9a7f-5d2b0c6e8f91 \
  -H "Authorization: Bearer vt_live_your-secret"

{
  "data": {
    "id": "pa_3f6e2a1c-8b4d-4c1e-9a7f-5d2b0c6e8f91",
    "status": "SUCCEEDED",
    "action": "leaves.request",
    "createdAt": "2026-09-24T09:15:02.114Z",
    "completedAt": "2026-09-24T09:15:24.870Z",
    "actingAsUserId": "...",
    "resource": {
      "type": "leaves",
      "id": "...",
      "url": "/v2/leaves/..."
    }
  }
}

Statuses

• PENDING: the change is still running. Poll again.
• SUCCEEDED: the main part of the change was applied. Read the resource from resource.url.
• FAILED: the change was rejected. See error.code.
• UNKNOWN: no result arrived within 15 minutes of the write. The change may or may not have been applied, so read the resource to check before you retry. A retry with the same Idempotency-Key never applies the change twice. If a result arrives later, the status still changes to SUCCEEDED or FAILED.

Poll every few seconds, and back off if the operation stays PENDING. Stop polling at UNKNOWN. Polling counts against your rate limit.

Who can read an operation

Only the API key that made the write can read its operation. No extra scope is needed. For any other key, and for operations older than the retention period, the API returns 404 RESOURCE_NOT_FOUND.

Retention

Operations are kept for 90 days.

Webhooks instead of polling

If you prefer push over polling, subscribe a webhook to these events:

• operation.completed: the operation reached SUCCEEDED.
• operation.failed: the operation reached FAILED.

Flow

Client guidance

• Never resubmit a 202 without the same Idempotency-Key. The change is already running. A new request without the key, or with a new key, can apply it twice. If you retry, use the same key and the same body, and you get the same operation back.
• Always send an Idempotency-Key on writes, so a timeout on your side is safe to retry.
• Treat 202 as "in progress", not as an error.
• Branch on status, and on error.code for FAILED operations.
• Set your HTTP client timeout above 20 seconds (30 seconds works well), so you receive the 202 instead of timing out yourself.