{
"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.
detail array whose items name the failing field and rule, with no code field and never the submitted value. Branch on the HTTP status first, then on code where one is present.
Use the code field in your integration logic to handle errors programmatically. The detail field is informational and may change between releases.
The codes below mirror the API’s error enum one-for-one and are grouped the same way. A handful of codes are defined in the contract but not currently emitted by any endpoint - these are called out as Reserved so you can safely ignore them until they ship.
Authentication and Authorization
INVALID_TOKEN
| HTTP Status | 401 |
|---|---|
| Meaning | The provided authentication token is invalid or malformed. |
| Common causes | Corrupted token, wrong signing key, or a KeyStone session JWT that failed verification. |
| Fix | Obtain a fresh access token. For Auth0 M2M tokens, verify your domain and audience configuration. |
TOKEN_EXPIRED
| HTTP Status | 401 |
|---|---|
| Meaning | Reserved. Defined for expired-token conditions. |
| Common causes | Not currently emitted - an expired KeyStone session token returns SESSION_TOKEN_EXPIRED, and expired Auth0 tokens surface as a generic 401 from the auth layer. |
| Fix | Request a new access token. |
MISSING_TOKEN
| HTTP Status | 401 |
|---|---|
| Meaning | Reserved. Defined for requests with no bearer token. |
| Common causes | Not currently emitted as a structured code - a request with no Authorization: Bearer <token> header is rejected by the auth layer with a generic 401. |
| 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, session token 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. |
PRINCIPAL_CONFLICT
| HTTP Status | 403 |
|---|---|
| Meaning | The token resolves to a customer platform organization but also carries KeyStone-internal operator permissions. This combination is not valid for a customer organization and the request is rejected as a safety measure. |
| Common causes | A KeyStone operator role was assigned inside a platform organization by mistake. |
| Fix | Contact KeyStone support - the role assignments for the affected user need to be corrected in Auth0. |
USER_TOKEN_REQUIRED
| HTTP Status | 403 |
|---|---|
| Meaning | The operation is only available to a person signed in through the dashboard, not to a machine credential. |
| Common causes | Calling a member role change or removal with an M2M or session token. |
| Fix | Perform the change from the dashboard, or with a user token that holds platform:members:manage. |
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 the timestamped signature header. |
| Fix | Send X-Callback-Signature: t=<unix_seconds>,v1=<hex hmac_sha256(secret, "{t}." + raw_body)> on every callback. See the provider callbacks guide. |
INVALID_CALLBACK_SIGNATURE
| HTTP Status | 401 |
|---|---|
| Meaning | The callback did not authenticate. Deliberately one answer for several causes, so an unauthenticated caller cannot probe which provider names are live. |
| Common causes | The {provider} path segment is not a registered provider; the signature timestamp is outside the acceptance window (300 seconds either side - stale or future-dated); the wrong signing secret was used, including another provider’s; the header is not in t=...,v1=... form (the retired bare-hex format fails this way); or the body bytes were re-serialized between signing and sending. |
| Fix | Sign the exact bytes you send with your own provider secret at send time, and check your clock. If a request that verifies locally is refused, your secret may have been rotated out or your provider name may not match the registered one - confirm both with KeyStone. |
CALLBACK_AUTH_NOT_CONFIGURED
| HTTP Status | 503 |
|---|---|
| Meaning | No callback provider is registered on this deployment, so no callback can authenticate. |
| Common causes | The CALLBACK_PROVIDER_SECRETS registry is unset or empty. |
| Fix | Register the provider and its signing secret in the deployment’s callback provider registry. 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 (direct lookup) or 422 (referenced during instruction/settlement creation, or a settlement’s pinned template config cannot be resolved) |
|---|---|
| Meaning | The referenced settlement template does not exist, or the template config a settlement pinned at creation can no longer be resolved. |
| Common causes | Wrong template_slug in an instruction, template deleted. A provider callback (POST /v1/callbacks/{provider}) or a compliance decision against a settlement whose pinned template version history is missing or no longer parses. |
| Fix | List available templates via GET /v1/settlement-templates and use a valid slug. The callback/decision 422 is deterministic - retrying cannot succeed; the settlement needs operator attention through the admin endpoints. |
PLATFORM_NOT_FOUND
| HTTP Status | 404 (direct lookup) or 422 (counterparty resolution during matching) |
|---|---|
| Meaning | The requested platform does not exist. |
| Common causes | Wrong platform ID, platform not yet registered, counterparty platform not resolvable. |
| Fix | Verify the platform ID or register the platform first. |
ENVIRONMENT_NOT_FOUND
| HTTP Status | 404 |
|---|---|
| Meaning | The requested environment does not exist, does not belong to your platform, or is not the one your credential is issued for. |
| Common causes | Wrong environment ID, environment belongs to a different platform, or an environment_id filter that names an environment other than the M2M credential’s own. |
| Fix | List your environments via GET /v1/platforms/me/environments. Each environment has its own M2M credential: use that environment’s client credentials rather than filtering with its ID. |
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. |
SESSION_NOT_FOUND
| HTTP Status | 404 |
|---|---|
| Meaning | The requested session token record does not exist in the calling credential’s environment. |
| Common causes | Wrong session ID, session already revoked or expired out of the store, or the token was minted in a different environment (revocation is environment-scoped, like minting). |
| Fix | Verify the session ID and revoke with the credentials of the environment that minted the token. Mint a new session token if it has been revoked. |
LEG_NOT_FOUND
| HTTP Status | 404 |
|---|---|
| Meaning | The requested leg index does not exist on the settlement. |
| Common causes | Requesting deposit calldata for a leg_index beyond the settlement’s leg count. |
| Fix | Use a valid leg index. The settlement response lists all legs and their indices. |
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. |
PRINCIPAL_NOT_FOUND
| HTTP Status | 404 |
|---|---|
| Meaning | The requested principal (screened entity) does not exist. |
| Common causes | Wrong principal ID, principal never created in this environment. |
| Fix | Verify the principal ID or external_reference used to look it up. |
Session Tokens
SESSION_TOKEN_EXPIRED
| HTTP Status | 401 |
|---|---|
| Meaning | The KeyStone session JWT has expired. |
| Common causes | The short-lived session token’s TTL elapsed. |
| Fix | Mint a new session token from your backend via the session token endpoint. |
SESSION_ESCALATION_DENIED
| HTTP Status | 403 |
|---|---|
| Meaning | A session token attempted to create another session token. |
| Common causes | Calling the session token creation endpoint while authenticated with a session token instead of a platform M2M token. |
| Fix | Create session tokens from your backend using your platform M2M credentials, not from a session token. |
SESSION_SETTLEMENT_SCOPE_DENIED
| HTTP Status | 403 |
|---|---|
| Meaning | The session token is restricted to specific settlements and the request fell outside that restriction. |
| Common causes | A settlement-scoped session token addressing a different settlement (get, events, related, compliance decision, deposit calldata), reading /related on a repo leg whose linked leg is outside the list, or using an endpoint a restricted token cannot access at all: creating settlements or any instructions endpoint. |
| Fix | Mint a session token scoped to the settlement you need to access (both legs, for a repo pair), or an unrestricted token (no settlement_ids) for widgets that submit instructions. |
SESSION_WRITE_DENIED
| HTTP Status | 403 |
|---|---|
| Meaning | A session token attempted a settlement-surface write that browser-delivered credentials cannot perform. |
| Common causes | Calling POST /v1/settlements, POST /v1/settlements/{id}/compliance-decision, or DELETE /v1/instructions/{id} with a session token. Holding settlements:write is not sufficient: the restriction is on the credential class, not the scope. |
| Fix | Perform the call from your backend with the environment’s M2M credentials. POST /v1/instructions is the one write a session token can perform. |
Deposit Calldata
DEPOSIT_SECRET_NOT_AVAILABLE
| HTTP Status | 422 |
|---|---|
| Meaning | The leg has no deposit secret available, so deposit calldata cannot be built. |
| Common causes | The settlement is not yet registered on-chain, or the leg does not carry a secret. |
| Fix | Wait until the settlement reaches AWAITING_DEPOSITS; the secret is generated at on-chain registration. |
NO_ESCROW_FOR_CHAIN
| HTTP Status | 422 |
|---|---|
| Meaning | No escrow contract is configured for the leg’s chain. |
| Common causes | The leg’s chain_id has no KeystoneSettlement deployment registered in this environment. |
| Fix | Use a supported chain. The error detail names the offending chain ID. |
LEG_NOT_DEPOSITABLE
| HTTP Status | 422 |
|---|---|
| Meaning | The leg does not require a deposit. |
| Common causes | Requesting deposit calldata for a receive-direction leg - only deliver legs are deposited. |
| Fix | Request calldata only for legs with direction: "deliver". |
OFFCHAIN_LEG
| HTTP Status | 422 |
|---|---|
| Meaning | The leg has no chain_id, so it has no on-chain deposit calldata. |
| Common causes | Requesting deposit calldata for an off-chain leg (for example an off-chain cash leg). |
| Fix | Off-chain legs are settled outside the escrow contract; do not request deposit calldata for them. |
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, a concurrent screening already in progress, or an instruction whose role already rests (pending_match, unexpired) on the same trade reference within your match scope. |
| Fix | Use a different value for the unique field, or retrieve the existing resource. For an instruction, cancel the resting one or wait for it to expire, then resubmit; a retry of the same submission reuses its original idempotency_key and returns the existing instruction. See submitting instructions. |
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, or receiving a callback for a settlement in an unexpected state. |
| Fix | Check the settlement’s current state before performing the operation. This refusal is deterministic: retrying the same request against the same state produces the same answer. |
SETTLEMENT_BUSY
| HTTP Status | 409 |
|---|---|
| Meaning | The settlement is momentarily unavailable to this request. This is the one 409 that means retry. |
| Common causes | Another operation holds the settlement (a chain event being applied, an operator intervention, a worker recording an on-chain outcome), or the settlement’s on-chain setup is being recorded and the request would move it out of COMPLIANCE_CLEARED. |
| Fix | Retry with backoff. The holder is another operation’s transaction, bounded by its own database work and chain-call timeouts, so a settlement held across an on-chain call stays busy for as long as that call’s timeout allows; a settlement whose on-chain setup is being recorded will be in AWAITING_DEPOSITS once it is, where a callback retry is an idempotent no-op, or back in COMPLIANCE_CLEARED if the setup halted, where the callback or decision applies. Sign callback retries freshly. |
NO_VALID_TRANSITION
| HTTP Status | 409 |
|---|---|
| Meaning | No valid state transition exists for the requested action. |
| Common causes | Attempting a transition the machine does not allow from the current state, a callback against a state owned by chain events or an operator, a provider callback against a state the settlement’s pinned template does not park on that provider (no webhook action naming it), or a provider callback against a compliance gate (a state with a compliance_check action bound), which callbacks can never resolve. |
| Fix | Review the settlement state machine. The settlement’s current state determines which transitions are legal and which provider, if any, may resolve it. A settlement parked at a compliance gate is resolved through the compliance-decision endpoint, not callbacks. |
INSTRUCTION_NOT_CANCELLABLE
| HTTP Status | 409 |
|---|---|
| Meaning | The instruction cannot be cancelled because it is no longer pending. |
| Common causes | Instruction already confirmed into a settlement, 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 terms on the opening settlement. |
| Fix | Verify the opening settlement has valid repo_terms (tenor_days, rate_bps, haircut_bps, margin band). |
ENVIRONMENT_DEACTIVATED
| HTTP Status | 409 |
|---|---|
| Meaning | The operation would create a new settlement in a deactivated environment, which accepts none. |
| Common causes | Triggering repo maturity for an opening with a party in a deactivated environment; provisioning demo settlements while the demo environment is deactivated. |
| Fix | Have a Keystone operator reactivate the environment, then retry. In-flight settlements are unaffected by deactivation; only the creation of new ones stops. |
PRINCIPAL_NO_LSEG_CASE
| HTTP Status | 409 |
|---|---|
| Meaning | The principal has no LSEG World-Check case to act on. |
| Common causes | Resolving a hit or triggering an LSEG action for a principal that was never screened through LSEG. |
| Fix | Screen the principal through LSEG before resolving a case for it. |
LSEG_TOOLKIT_STALE
| HTTP Status | 503 |
|---|---|
| Meaning | The cached LSEG resolution reference data (risk/reason toolkit) is stale or does not match the live toolkit. |
| Common causes | The LSEG reference data changed upstream and the local cache has not refreshed yet. |
| Fix | Retry after the toolkit cache refreshes. If it persists, contact your KeyStone administrator. |
MEMBER_CHANGE_IN_PROGRESS
| HTTP Status | 409 |
|---|---|
| Meaning | Another member change is being applied for this organization. Member changes are applied one at a time per organization so that the check keeping at least one member manager cannot be raced. |
| Common causes | Two administrators editing members at the same moment, or a retry sent before the first request finished. |
| Fix | Retry once the other change completes. A change whose process died mid-way releases the organization when its lock expires, within two minutes. |
Validation
VALIDATION_ERROR
| HTTP Status | 422 (default) or 400 |
|---|---|
| Meaning | The request failed validation. |
| Common causes | Invalid request body, missing required fields, type mismatches, a settlement domain rule rejection, or a resource ceiling reached (see webhook limits). |
| Fix | Review the request body against the API documentation for the endpoint. The detail field names the ceiling when one was exceeded. |
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. |
UNSUPPORTED_CHAIN_COMBINATION
| HTTP Status | 422 |
|---|---|
| Meaning | The legs of the request (or of a matched instruction pair) reference a combination of chains the platform cannot settle together. Support is capability-driven: every chain in the leg set must have an active settlement contract in this deployment, and where the set spans more than one chain, the routers on those chains must be peered. Read the settleable set from GET /v1/chains. |
| Common causes | Legs of one instruction or settlement carry different chain_id values, or two matched instructions place their legs on different chains, and that specific combination is not (yet) a supported settlement lane. |
| Fix | Use a supported combination. Today that means all legs on the same chain_id, or omitting chain_id to use the settlement chain. The error detail lists the offending chain IDs. |
UNSUPPORTED_SETTLEMENT_CHAIN
| HTTP Status | 422 |
|---|---|
| Meaning | The legs reference a chain this environment cannot settle on. The chain count is fine (see UNSUPPORTED_CHAIN_COMBINATION for that case), but the named chain has no active settlement contract in this deployment. |
| Common causes | All legs carry a chain_id for a network the environment does not settle on - for example legs on Ethereum Sepolia while the deployment settles on Base Sepolia. |
| Fix | Use a settleable chain (the error detail lists both the offending chains and the chains this environment settles on), or omit chain_id to use the settlement chain. |
NON_INTEGRAL_QUANTITY
| HTTP Status | 422 |
|---|---|
| Meaning | A leg quantity has a fractional part. Quantities are integer base units (the instrument’s smallest on-chain unit); the settlement contract escrows whole uint256 amounts, so a fractional quantity cannot settle. |
| Common causes | Sending display-denominated amounts (for example 1.5 tokens) instead of base units, or deriving amounts with division that leaves a fractional remainder. |
| Fix | Convert amounts to integer base units before submitting (multiply by 10^decimals of the instrument). The error detail names each offending instrument and quantity. |
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. |
LAST_MEMBER_MANAGER
| HTTP Status | 422 |
|---|---|
| Meaning | The change would leave the organization without any member whose roles grant platform:members:manage, so nobody could manage members afterwards. |
| Common causes | Demoting or removing the only administrator. |
| Fix | Grant a manager role to another member first, then retry. |
INVALID_TARGET_STATE
| HTTP Status | 422 |
|---|---|
| Meaning | The target state is not a valid state of the settlement’s machine. |
| Common causes | Typo in state name during an admin manual transition. |
| Fix | Use a state that exists in the settlement’s state machine. |
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 | A callback arrived for a state that has no defined next transition. |
| Fix | Check the settlement’s current state; the callback may be arriving out of order. |
PRINCIPAL_REFERENCE_MISSING
| HTTP Status | 422 |
|---|---|
| Meaning | Reserved. Defined for a missing principal reference. |
| Common causes | Not currently emitted by any endpoint. |
| Fix | No action required. |
PRINCIPAL_REFERENCE_MISMATCH
| HTTP Status | 422 |
|---|---|
| Meaning | Reserved. Defined for a principal reference that does not match. |
| Common causes | Not currently emitted by any endpoint. |
| Fix | No action required. |
UNRECOGNIZED_CLIENT
| HTTP Status | 422 |
|---|---|
| Meaning | The auth0_client_id supplied when creating an environment or rotating its secret is not a client authorized for the KeyStone API. |
| Common causes | A client id copied from the wrong tenant or application; a client that exists but has not been granted access to the KeyStone API; a typo in the id. |
| Fix | Use the client id of a machine-to-machine application authorized for the KeyStone API. See environments. |
Rate Limiting
RATE_LIMIT_EXCEEDED
| HTTP Status | 429 |
|---|---|
| Meaning | Too many requests against your own limit: the per-environment rate limit, or the platform-wide limit that covers user-token requests sent without X-Keystone-Environment. |
| Common causes | High request volume, burst traffic, tight polling loops. User-token requests without X-Keystone-Environment share one platform-wide window at the default limit instead of the environment’s own. |
| 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. Send X-Keystone-Environment on every user-token request so it counts against your environment’s limit. Use webhooks instead of polling where possible. |
RATE_LIMIT_UNATTRIBUTED
| HTTP Status | 429 |
|---|---|
| Meaning | Too many requests that KeyStone could not attribute to any platform or environment, counted against a shared per-IP ceiling that is separate from and lower than your own limits. |
| Common causes | A retry loop on failing authentication, requests with an expired or malformed token, or unauthenticated traffic from the same address. |
| Fix | Fix the credentials so requests authenticate and count against your own limit; do not retry harder. The Retry-After header reports when the ceiling frees a slot. |
RATE_LIMIT_CREDENTIAL_ISSUANCE
| HTTP Status | 429 |
|---|---|
| Meaning | Too many requests to a route whose response can carry a credential: a session token, a rotated client or webhook secret, a new webhook endpoint’s secret, or an invitation link, the invitation listing included. These routes are counted on their own window, per environment, or per platform for a user credential sent without an environment, separate from and lower than your environment limit. Each publishes the 429 in the API reference. |
| Common causes | Minting a session token per request instead of per user session; a retry loop around a rotate call. |
| Fix | Mint one session token per user session and reuse it for its lifetime. The Retry-After header reports when the window frees a slot. Contact support if your widget traffic legitimately exceeds the limit. |
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 or 503 |
|---|---|
| Meaning | An external service integration failed. |
| Common causes | Downstream service (for example an LSEG or wallet-screening provider) unavailable, timing out, or returning errors. |
| Fix | Retry the request with exponential backoff. Check the KeyStone status page for known outages. |