Error Handling

HTTP status codes

Code	Meaning	When
`200`	Success	GET requests
`201`	Created	POST that creates a resource, and idempotent replays of a create
`400`	Bad request	Malformed JSON, missing required fields
`401`	Unauthorized	Invalid or expired JWT
`403`	Forbidden	Insufficient scopes/permissions
`404`	Not found	Resource does not exist or not in your environment
`409`	Conflict	Duplicate unique value (webhook URL, environment slug, CIDR range, a resting same-role instruction), invalid state transition
`422`	Validation error	Valid 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"
    }
  ]
}

Each item carries exactly these three keys. loc names the field (or query, path, or header parameter) that failed, msg states the rule it broke, and type is a stable machine-readable identifier for that rule. The submitted value does not come back as a field of the error: input, ctx and url are stripped from every item, because error responses travel into logs, error trackers and support tickets, and a submitted value can be a credential, as a webhook endpoint URL is. Inside loc, an element can be a key name you sent (for example when a request carries a field the schema does not define), and every loc element is truncated to its first 32 characters. Inside msg, validators written for this API name the rule that was broken and the valid options rather than repeating what you sent, though an underlying parser may quote a short fragment of a malformed value when naming where parsing stopped. Treat a 422 body with the same care as the request that produced it, and keep it out of public channels.

Updating a field vs. clearing it

On PATCH endpoints, omitting a field always leaves the stored value unchanged. Sending an explicit null is only accepted for fields that can genuinely be cleared (such as a webhook endpoint’s description). For any other field, null is rejected with a 422 whose type is null_not_allowed - there is no field where sending null means “keep the current value”.

Idempotency

Settlement creation and instruction submission are idempotent via idempotency_key, scoped to your environment. If you send the same key:

First call: creates the resource (201)
Any later call, including one that races the first: returns the existing resource (201)

Keys starting with match- are reserved for keys KeyStone derives and answer 422. Every other key is yours, including one containing -CLOSE-, and makes creation calls safe to retry on network errors.

Retrying failed requests

Scenario	Retry?	Strategy
Network timeout	Yes	Retry with same idempotency key
5xx server error	Yes	Exponential backoff
401 Unauthorized	Yes	Refresh token first, then retry
400/422 Validation	No	Fix the request
409 Conflict	Only `SETTLEMENT_BUSY`	`SETTLEMENT_BUSY`: retry after a short delay. Any other code: check current state, decide next action
404 Not Found	No	Verify 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 confirmed, 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 (for example, a required party role is missing).

On-chain error handling

When the KeystoneSettlement contract rejects an operation (e.g. the compliance gate is closed at execution time, or a deposit fails the commitment check), the transaction reverts and the settlement remains in its current state. A closed gate never blocks deposits - the settlement simply stays registered until attestation lands. If the settlement reaches its timeout_at deadline, any depositor (or the operator) can call claimTimeout() on the KeystoneSettlement contract, then reclaim deposits per leg via claimRefund(). Neither path can be paused or depends on KeyStone being up - every party with funds at stake can recover them itself.

Webhook error handling

If your webhook endpoint returns a non-2xx response:

KeyStone retries with exponential backoff
Failed deliveries are logged in the delivery log
The settlement continues regardless (webhooks are notifications, not blocking)

Always handle webhooks idempotently - you may receive the same event more than once.

Getting Started

Core Concepts

Guides

Smart Contracts

HTTP status codes

Error response format

Updating a field vs. clearing it

Idempotency

Retrying failed requests

Settlement-specific errors

Compliance decision on wrong state

Instruction not cancellable

Template validation failures

On-chain error handling

Webhook error handling

​HTTP status codes

​Error response format

​Updating a field vs. clearing it

​Idempotency

​Retrying failed requests

​Settlement-specific errors

​Compliance decision on wrong state

​Instruction not cancellable

​Template validation failures

​On-chain error handling

​Webhook error handling

HTTP status codes

Error response format

Updating a field vs. clearing it

Idempotency

Retrying failed requests

Settlement-specific errors

Compliance decision on wrong state

Instruction not cancellable

Template validation failures

On-chain error handling

Webhook error handling