Error Codes - KeyStone OS

Every error response from the KeyStone API includes a structured body with three fields:

{
  "detail": "Human-readable error message",
  "code": "ERROR_CODE",
  "docs_url": "https://docs.keystoneos.xyz/guides/error-codes#error-code"
}

detail - A human-readable description of what went wrong.
code - A machine-readable error code for programmatic handling.
docs_url - A direct link to the documentation for this specific error.

Use the code field in your integration logic to handle errors programmatically. The detail field is informational and may change between releases.

Authentication and Authorization

INVALID_TOKEN

HTTP Status	401
Meaning	The provided authentication token is invalid or malformed.
Common causes	Expired JWT, corrupted token, wrong signing key.
Fix	Obtain a fresh access token from Auth0. Verify your Auth0 domain and audience configuration.

TOKEN_EXPIRED

HTTP Status	401
Meaning	The authentication token has expired.
Common causes	Token TTL exceeded without refresh.
Fix	Request a new access token from Auth0 using your client credentials.

MISSING_TOKEN

HTTP Status	401
Meaning	No authentication token was provided in the request.
Common causes	Missing `Authorization: Bearer <token>` header.
Fix	Include a valid Bearer token in the Authorization header.

INSUFFICIENT_SCOPES

HTTP Status	403
Meaning	The authenticated token does not have the required permissions for this endpoint.
Common causes	M2M client missing required scopes, user missing required Auth0 permissions.
Fix	Verify your Auth0 application has the required scopes/permissions assigned. Check the endpoint documentation for required permissions.

NO_PLATFORM_CONTEXT

HTTP Status	403
Meaning	No platform could be resolved from the authentication context.
Common causes	Unregistered M2M client, suspended platform, user not a member of any organization.
Fix	Ensure your M2M client is registered via platform onboarding. Check that the platform is active.

NO_ENVIRONMENT_CONTEXT

HTTP Status	403
Meaning	No environment could be resolved from the authentication context.
Common causes	For M2M tokens: the client_id is not linked to an environment. For user tokens: missing `X-Keystone-Environment` header.
Fix	For M2M: verify the client_id is registered to an environment. For user tokens: include the `X-Keystone-Environment` header with the environment slug.

IP_NOT_ALLOWED

HTTP Status	403
Meaning	The request IP address is not in the environment’s IP allowlist.
Common causes	Making API calls from an IP not added to the allowlist, IP changed after allowlist was configured.
Fix	Add your current IP or CIDR range to the environment’s allowlist via the API or dashboard.

AUTH_CONTEXT_NOT_RESOLVED

HTTP Status	500
Meaning	Internal error - the authentication context was not properly initialized.
Common causes	Server-side route misconfiguration.
Fix	This is an internal error. Contact KeyStone support if it persists.

Callback Authentication

MISSING_CALLBACK_SIGNATURE

HTTP Status	401
Meaning	The callback request is missing the `X-Callback-Signature` header.
Common causes	Provider integration not sending HMAC signature.
Fix	Ensure the callback sender includes a valid `X-Callback-Signature` header with an HMAC-SHA256 signature of the request body.

INVALID_CALLBACK_SIGNATURE

HTTP Status	401
Meaning	The callback signature does not match the expected HMAC-SHA256 value.
Common causes	Wrong signing secret, request body modified in transit, encoding mismatch.
Fix	Verify the signing secret matches on both sides. Ensure the signature is computed over the exact request body bytes.

CALLBACK_AUTH_NOT_CONFIGURED

HTTP Status	503
Meaning	The callback signing secret is not configured on the server.
Common causes	Missing `CALLBACK_SIGNING_SECRET` environment variable.
Fix	Configure the callback signing secret in the server environment. Contact your KeyStone administrator.

Not Found

SETTLEMENT_NOT_FOUND

HTTP Status	404
Meaning	The requested settlement does not exist or is not accessible in your environment.
Common causes	Wrong settlement ID, settlement belongs to a different environment.
Fix	Verify the settlement ID. Ensure you are querying the correct environment.

TEMPLATE_NOT_FOUND

HTTP Status	404 or 422
Meaning	The referenced settlement template does not exist.
Common causes	Wrong template_id in settlement creation, template deleted.
Fix	List available templates via `GET /v1/settlement-templates` and use a valid template_id.

PLATFORM_NOT_FOUND

HTTP Status	404
Meaning	The requested platform does not exist.
Common causes	Wrong platform ID, platform not yet registered.
Fix	Verify the platform ID or register the platform first.

ENVIRONMENT_NOT_FOUND

HTTP Status	404
Meaning	The requested environment does not exist or does not belong to your platform.
Common causes	Wrong environment ID, environment belongs to a different platform.
Fix	List your environments via `GET /v1/platforms/me/environments`.

INSTRUCTION_NOT_FOUND

HTTP Status	404
Meaning	The requested settlement instruction does not exist.
Common causes	Wrong instruction ID, instruction belongs to a different platform.
Fix	Verify the instruction ID and that it belongs to your platform.

WEBHOOK_ENDPOINT_NOT_FOUND

HTTP Status	404
Meaning	The requested webhook endpoint does not exist in your environment.
Common causes	Wrong endpoint ID, endpoint deleted, querying wrong environment.
Fix	List webhook endpoints via `GET /v1/platforms/me/webhooks`.

IP_RANGE_NOT_FOUND

HTTP Status	404
Meaning	The requested IP allowlist entry does not exist.
Common causes	Wrong IP entry ID, entry already deleted.
Fix	List current entries via `GET /v1/platforms/me/allowed-ips`.

MEMBER_NOT_FOUND

HTTP Status	404
Meaning	The specified member was not found in the organization.
Common causes	Wrong user ID, member already removed from organization.
Fix	List current members via `GET /v1/platforms/me/members`.

PROVIDER_NOT_FOUND

HTTP Status	404
Meaning	The requested external provider is not registered.
Common causes	Typo in provider name, provider not configured.
Fix	List available providers via `GET /v1/admin/providers/health`.

NOT_REPO_SETTLEMENT

HTTP Status	404
Meaning	The settlement is not part of a repo (repurchase agreement) and has no related settlements.
Common causes	Calling the related settlements endpoint on a non-repo settlement.
Fix	This endpoint only works for settlements with `trade_type` of `repo_open` or `repo_close`.

Conflict

DUPLICATE_RESOURCE

HTTP Status	409
Meaning	A resource with the same unique identifier already exists.
Common causes	Duplicate webhook URL, duplicate environment slug, duplicate CIDR range, duplicate template slug.
Fix	Use a different value for the unique field, or retrieve the existing resource.

SETTLEMENT_STATE_CONFLICT

HTTP Status	409
Meaning	The settlement is not in the expected state for this operation.
Common causes	Submitting a compliance decision for a settlement not in compliance checking, receiving a callback for a settlement in an unexpected state.
Fix	Check the settlement’s current state before performing the operation.

NO_VALID_TRANSITION

HTTP Status	409
Meaning	No valid state transition exists for the requested action.
Common causes	Template configuration does not define a next state for the current state, attempting a forbidden transition.
Fix	Review the settlement template’s transition rules. For compliance decisions, ensure the template defines the appropriate next states.

INSTRUCTION_NOT_CANCELLABLE

HTTP Status	409
Meaning	The instruction cannot be cancelled because it is no longer pending.
Common causes	Instruction already matched, already cancelled, or expired.
Fix	Only instructions with status `pending_match` can be cancelled.

NOT_REPO_OPEN

HTTP Status	409
Meaning	The settlement is not a repo_open settlement.
Common causes	Attempting to trigger maturity on a non-repo or repo_close settlement.
Fix	This operation only applies to settlements with `trade_type: repo_open`.

SETTLEMENT_NOT_FINALIZED

HTTP Status	409
Meaning	The settlement must be in FINALIZED state for this operation.
Common causes	Attempting to trigger repo maturity before the opening settlement is finalized.
Fix	Wait for the settlement to reach FINALIZED state.

CLOSING_ALREADY_EXISTS

HTTP Status	409
Meaning	A closing settlement already exists for this repo opening.
Common causes	Triggering maturity twice on the same repo_open settlement.
Fix	The closing settlement was already created. Query it via the related settlements endpoint.

CLOSING_CREATION_FAILED

HTTP Status	409
Meaning	The closing settlement could not be created.
Common causes	Missing or invalid repo metadata on the opening settlement.
Fix	Verify the opening settlement has valid `repo_terms` (tenor_days, rate_bps, haircut_bps, margin band).

NO_ROLLBACK_STATE

HTTP Status	409
Meaning	The template has no ROLLED_BACK or failure state defined for rollback.
Common causes	Template configuration missing failure_states.
Fix	Update the template to include a ROLLED_BACK state in its failure_states.

Validation

VALIDATION_ERROR

HTTP Status	422
Meaning	The request failed validation.
Common causes	Invalid request body, missing required fields, type mismatches.
Fix	Review the request body against the API documentation for the endpoint.

NO_FIELDS_PROVIDED

HTTP Status	422
Meaning	A PATCH request was sent with no fields to update.
Common causes	Empty request body or all fields excluded.
Fix	Include at least one field to update in the request body.

INVALID_PARTY_CONFIGURATION

HTTP Status	422
Meaning	The settlement party configuration is invalid.
Common causes	Missing required roles (e.g. buyer or seller), unknown roles, duplicate participants, missing wallet addresses.
Fix	Review the template’s `required_roles` and ensure all required parties are provided with valid data.

TEMPLATE_INACTIVE

HTTP Status	422
Meaning	The referenced template is not active and cannot be used for new settlements.
Common causes	Template deactivated by admin.
Fix	Use an active template. List available templates via `GET /v1/settlement-templates`.

NO_AUTH0_ORGANIZATION

HTTP Status	422
Meaning	The platform has no linked Auth0 Organization.
Common causes	Platform was created without Auth0 integration, or the organization link was broken.
Fix	Contact KeyStone support to link an Auth0 Organization to the platform.

SELF_ACTION_FORBIDDEN

HTTP Status	422
Meaning	You cannot perform this action on yourself.
Common causes	Attempting to change your own roles or remove yourself from the organization.
Fix	Ask another admin to perform this action.

INVALID_TARGET_STATE

HTTP Status	422
Meaning	The target state is not defined in the settlement template.
Common causes	Typo in state name during admin manual transition.
Fix	Use a state that exists in the template’s state list.

NO_FAILURE_STATE

HTTP Status	422
Meaning	The template has no failure state defined.
Common causes	Template configuration missing failure_states for failure callbacks.
Fix	Update the template to include appropriate failure states.

CANNOT_RESOLVE_TARGET_STATE

HTTP Status	422
Meaning	The system cannot determine the next state for a callback in the current settlement state.
Common causes	Template transitions do not define a next state for the current state.
Fix	Review the template’s transition configuration.

Rate Limiting

RATE_LIMIT_EXCEEDED

HTTP Status	429
Meaning	Too many requests. The per-environment rate limit has been exceeded.
Common causes	High request volume, burst traffic, tight polling loops.
Fix	Reduce request frequency. Check the `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After` response headers to understand the limits and when to retry. Use webhooks instead of polling where possible.

External Service Failures

AUTH0_ERROR

HTTP Status	502
Meaning	An operation against Auth0 failed.
Common causes	Auth0 service outage, rate limiting by Auth0, invalid Auth0 configuration.
Fix	Retry the request. If the issue persists, check the Auth0 status page.

EXTERNAL_SERVICE_ERROR

HTTP Status	502
Meaning	An external service integration failed.
Common causes	Downstream service unavailable, timeout, or returning errors.
Fix	Retry the request with exponential backoff. Check the KeyStone status page for known outages.

​Authentication and Authorization

​INVALID_TOKEN

​TOKEN_EXPIRED

​MISSING_TOKEN

​INSUFFICIENT_SCOPES

​NO_PLATFORM_CONTEXT

​NO_ENVIRONMENT_CONTEXT

​IP_NOT_ALLOWED

​AUTH_CONTEXT_NOT_RESOLVED

​Callback Authentication

​MISSING_CALLBACK_SIGNATURE

​INVALID_CALLBACK_SIGNATURE

​CALLBACK_AUTH_NOT_CONFIGURED

​Not Found

​SETTLEMENT_NOT_FOUND

​TEMPLATE_NOT_FOUND

​PLATFORM_NOT_FOUND

​ENVIRONMENT_NOT_FOUND

​INSTRUCTION_NOT_FOUND

​WEBHOOK_ENDPOINT_NOT_FOUND

​IP_RANGE_NOT_FOUND

​MEMBER_NOT_FOUND

​PROVIDER_NOT_FOUND

​NOT_REPO_SETTLEMENT

​Conflict

​DUPLICATE_RESOURCE

​SETTLEMENT_STATE_CONFLICT

​NO_VALID_TRANSITION

​INSTRUCTION_NOT_CANCELLABLE

​NOT_REPO_OPEN

​SETTLEMENT_NOT_FINALIZED

​CLOSING_ALREADY_EXISTS

​CLOSING_CREATION_FAILED

​NO_ROLLBACK_STATE

​Validation

​VALIDATION_ERROR

​NO_FIELDS_PROVIDED

​INVALID_PARTY_CONFIGURATION

​TEMPLATE_INACTIVE

​NO_AUTH0_ORGANIZATION

​SELF_ACTION_FORBIDDEN

​INVALID_TARGET_STATE

​NO_FAILURE_STATE

​CANNOT_RESOLVE_TARGET_STATE

​Rate Limiting

​RATE_LIMIT_EXCEEDED

​External Service Failures

​AUTH0_ERROR

​EXTERNAL_SERVICE_ERROR