Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
HTTP status codes

CodeMeaningWhen
200SuccessGET requests, idempotent retries
201CreatedPOST that creates a resource
400Bad requestMalformed JSON, missing required fields
401UnauthorizedInvalid or expired JWT
403ForbiddenInsufficient scopes/permissions
404Not foundResource does not exist or not in your environment
409ConflictDuplicate idempotency key, invalid state transition
422Validation errorValid JSON but business rule violated

​
Error response format

All errors return a consistent structure: 
{
  "detail": "Human-readable error message"
}
For validation errors (422): 
{
  "detail": [
    {
      "loc": ["body", "parties", 0, "role"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

​
Idempotency

Instruction submission is idempotent via idempotency_key. If you send the same key:
  • First call: creates the instruction (201)
  • Subsequent calls: returns the existing instruction (200)
This makes all submission calls safe to retry on network errors.

​
Retrying failed requests

ScenarioRetry?Strategy
Network timeoutYesRetry with same idempotency key
5xx server errorYesExponential backoff
401 UnauthorizedYesRefresh token first, then retry
400/422 ValidationNoFix the request
409 ConflictNoCheck current state, decide next action
404 Not FoundNoVerify the resource ID

​
Settlement-specific errors

​
Compliance decision on wrong state

// 409
{"detail": "Settlement is not awaiting a compliance decision"}
The settlement has already advanced past the compliance check. Query the current state to see where it is.

​
Instruction not cancellable

// 409
{"detail": "Instruction is not cancellable"}
Only instructions with status: pending_match can be cancelled. Instructions that have already been matched, expired, or cancelled cannot be changed.

​
Template validation failures

// 422
{"detail": "Missing required role: buyer"}
The settlement instruction does not satisfy the template’s required_roles or required_leg_types.

​
On-chain error handling

When the SettlementCoordinator rejects a transition (e.g. gate check fails), the contract reverts. The settlement remains in its current state. The engine logs the rejection and can retry when conditions change. If the settlement reaches its timeout_at deadline, anyone can call timeout() on the SettlementCoordinator to trigger rollback. This is permissionless and does not depend on KeyStone.

​
Webhook error handling

If your webhook endpoint returns a non-2xx response:
  1. KeyStone retries with exponential backoff
  2. Failed deliveries are logged in the delivery log
  3. The settlement continues regardless (webhooks are notifications, not blocking)
Always handle webhooks idempotently - you may receive the same event more than once.