> ## 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. # Error Codes > Complete reference for machine-readable error codes returned by the KeyStone API. Every error response from the KeyStone API includes a structured body with three fields: ```json theme={null} { "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 ` 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](https://status.auth0.com/). | ### 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. |