Idempotency API Reference

Complete documentation for idempotency checking with check-lock.

Check Lock

Endpoint: POST /v1/check-lock

Check if an action is new or a duplicate.

Request

curl -X POST https://api.onceonly.tech/v1/check-lock \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "payment_invoice_123",
    "ttl": 3600,
    "metadata": {
      "invoice_id": "INV-123",
      "amount_usd": 99.99
    }
  }'

Request Body

Field	Type	Required	Description
`key`	string	✓	Unique action identifier (1-256 chars)
`ttl`	integer	-	Lock duration in seconds (default depends on plan/server config; e.g. Free=60, Starter=3600, Pro=21600, Agency=86400)
`metadata`	object	-	Additional data (max 2048 bytes)

Response - New Action

{
  "success": true,
  "status": "locked",
  "key": "payment_invoice_123",
  "ttl": 3600,
  "first_seen_at": null
}

Response - Duplicate

{
  "success": false,
  "status": "duplicate",
  "key": "payment_invoice_123",
  "ttl": 3600,
  "first_seen_at": "2025-01-15T10:30:00Z"
}

Note: If the server is configured with DUPLICATE_STATUS_CODE=409, duplicates return HTTP 409 instead of 200:
{
  "detail": {
    "error": "Duplicate blocked",
    "first_seen_at": "2025-01-15T10:30:00Z"
  }
}

Error Responses

422 - Validation Error (FastAPI/Pydantic)

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "key"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

401 - Missing Authorization

{
  "detail": "Missing Authorization Bearer token"
}

403 - Invalid or Disabled API Key

{
  "detail": "Invalid API key"
}

402 - Plan Limit Reached

{
  "detail": {
    "error": "payment_required",
    "highlights": "Plan limit reached",
    "plan": "free",
    "limit": 1000,
    "usage": 1001,
    "upgrade_url": ""
  }
}

429 - Rate Limited

{
  "detail": { "error": "rate_limited" }
}

Status Codes

Code	Meaning
200	Success (new or duplicate)
402	Plan limit reached
409	Duplicate blocked (optional)
401	Missing Authorization
403	Invalid or disabled API key
422	Validation error
429	Rate limited

Examples

Python

import os
from onceonly import OnceOnly

client = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"])

# Usage
lock = client.check_lock(key="payment_123", ttl=3600)
if not lock.duplicate:
    # New action - proceed
    execute_payment()
else:
    # Duplicate - use cached result
    return get_cached_result("payment_123")

cURL

# First call
curl -X POST https://api.onceonly.tech/v1/check-lock \
  -H "Authorization: Bearer once_live_xxxxx" \
  -d '{"key":"payment_123"}'
# → {"status":"locked"}

# Retry within TTL
curl -X POST https://api.onceonly.tech/v1/check-lock \
  -H "Authorization: Bearer once_live_xxxxx" \
  -d '{"key":"payment_123"}'
# → {"status":"duplicate"}