Operations

Errors, retries, and limits

Build agents that retry safely, respect plan entitlements, and remain predictable under load.

Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Keyword must be at least 3 characters",
    "requestId": "...",
    "details": [{ "path": "value", "message": "..." }]
  }
}

400

VALIDATION_ERROR

Malformed or invalid input.

401

UNAUTHORIZED

Missing, expired, revoked, or wrong-resource token.

402

USAGE_LIMIT

A plan or safety cap is exhausted.

403

FORBIDDEN

Scope or project role is insufficient.

404

NOT_FOUND

Missing or inaccessible resource.

409

CONFLICT

Idempotency mismatch, in-flight duplicate, or state conflict.

429

RATE_LIMIT

Machine-call budget exhausted; honor Retry-After.

500/503

INTERNAL_ERROR

Transient service failure; retry a keyed write.

Idempotency

Use a unique 8–128 character Idempotency-Key for writes. A completed result is replayed for 24 hours. Concurrent duplicates return IDEMPOTENCY_IN_PROGRESS; the same key with different input returns IDEMPOTENCY_MISMATCH.

Retry rule

Retry 429 and transient 5xx responses with exponential backoff and jitter. Only retry writes when they carry the same idempotency key and identical input.

Machine rate limits

Rate limits are enforced in shared Redis buckets and fail closed in production if the limiter is unavailable. Paid workspaces receive up to 240 reads and 60 writes per minute; trial workspaces receive up to 90 reads and 30 writes per minute. Expensive operations are capped at 10 per minute.

Trial workspaces also share daily ceilings of 5,000 reads, 500 writes, and 100 expensive operations. These are abuse ceilings, not entitlements, and may be lowered for safety. Multiple API keys and OAuth connections share the same workspace buckets.

Product and provider limits

Agent access does not change Stalkr’s product economics. Trial users can call every operation, but the existing three-keyword, 100-mention, seven-day scan, scan-request, project, member, alert, and provider-budget controls remain enforced in the same services as the dashboard.

Trial workspaces can hold five active API keys, five webhook endpoints, and five OAuth MCP connections. Paid limits are 10 keys, 20 webhooks, and 20 OAuth connections. Creating keys or reading existing data does not consume mention/provider credits; creating keywords, triggering provider syncs, fetching mentions, and delivering alerts continue to use their normal product controls.