Skip to main content

​
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 doesn’t 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

Settlement creation is idempotent via idempotency_key. If you send the same key:
  • First call: creates the settlement (201)
  • Subsequent calls: returns the existing settlement (200)
This makes all creation 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.

​
Confirm/reject on non-cross-platform settlement

// 409
{"detail": "Settlement is not cross-platform"}
Only settlements with settlement_type: "cross_platform" support the confirm/reject endpoints.

​
Template validation failures

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

​
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.