Error Codes
Every standardized error code the Checkpoint platform returns, grouped by category, with HTTP status and message
This page is generated from the shared error registry in packages/checkpoint-shared/src/constants/errors.ts. Do not edit it by hand: run pnpm --filter @kya-os/checkpoint-shared run errors:docs to regenerate it, and CI fails any change that leaves this page out of date with the registry.
Error responses carry these codes in the error.code field of the standard error envelope, alongside a human-readable message. The HTTP status column shows the status returned for that code. A status marked "(default)" means the code has no explicitly assigned status in the registry and falls back to 500. A few endpoints also emit route-local codes that are not part of this registry, for example PROVISIONING_INVALID_REQUEST from the provisioning API.
Authentication
| Code | HTTP status | Message |
|---|---|---|
AUTH_INVALID_API_KEY | 401 | The provided API key is invalid |
AUTH_EXPIRED_API_KEY | 401 | The API key has expired |
AUTH_INVALID_TOKEN | 401 | The provided token is invalid |
AUTH_EXPIRED_TOKEN | 401 | The token has expired |
AUTH_MISSING_CREDENTIALS | 401 | Authentication credentials are required |
AUTH_UNAUTHORIZED | 401 | You are not authorized to perform this action |
AUTH_MANAGEMENT_TOKEN_NOT_ACCEPTED | 401 | Management session tokens are accepted only by /api/cli/management routes |
AUTH_INVALID_PIXEL_ID | 500 (default) | The provided pixel ID is invalid |
AUTH_INVALID_SECRET_KEY | 500 (default) | The provided secret key is invalid |
Validation
| Code | HTTP status | Message |
|---|---|---|
VALIDATION_INVALID_REQUEST | 400 | The request is invalid |
VALIDATION_MISSING_REQUIRED_FIELD | 400 | A required field is missing |
VALIDATION_INVALID_FIELD_TYPE | 400 | Field type is invalid |
VALIDATION_INVALID_FIELD_VALUE | 400 | Field value is invalid |
VALIDATION_FIELD_TOO_LONG | 500 (default) | Field value exceeds maximum length |
VALIDATION_FIELD_TOO_SHORT | 500 (default) | Field value is below minimum length |
VALIDATION_INVALID_EMAIL | 500 (default) | Invalid email address format |
VALIDATION_INVALID_URL | 500 (default) | Invalid URL format |
VALIDATION_INVALID_UUID | 500 (default) | Invalid UUID format |
VALIDATION_INVALID_IP_ADDRESS | 500 (default) | Invalid IP address format |
VALIDATION_INVALID_USER_AGENT | 500 (default) | Invalid or missing user agent |
VALIDATION_BAD_REQUEST | 400 | Bad request |
VALIDATION_INVALID_START_DATE | 400 | Invalid request data |
VALIDATION_INVALID_END_DATE | 400 | Invalid request data |
VALIDATION_INVALID_DATE_RANGE | 400 | Invalid request data |
Detection
| Code | HTTP status | Message |
|---|---|---|
DETECTION_FAILED | 500 (default) | Agent detection failed |
DETECTION_INSUFFICIENT_DATA | 500 (default) | Insufficient data for detection |
DETECTION_PATTERN_MATCH_FAILED | 500 (default) | Pattern matching failed |
DETECTION_WASM_NOT_LOADED | 500 (default) | WASM module is not loaded |
DETECTION_WASM_EXECUTION_FAILED | 500 (default) | WASM execution failed |
DETECTION_CONFIDENCE_BELOW_THRESHOLD | 500 (default) | Detection confidence below threshold |
DETECTION_SIGNATURE_VERIFICATION_FAILED | 500 (default) | Signature verification failed |
Rate limiting
| Code | HTTP status | Message |
|---|---|---|
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded |
RATE_LIMIT_BURST_EXCEEDED | 429 | Burst limit exceeded |
RATE_LIMIT_DAILY_EXCEEDED | 429 | Daily request limit exceeded |
RATE_LIMIT_MONTHLY_EXCEEDED | 500 (default) | Monthly request limit exceeded |
RATE_LIMIT_CONCURRENT_EXCEEDED | 500 (default) | Concurrent request limit exceeded |
RATE_LIMIT_QUOTA_EXCEEDED | 500 (default) | Account quota exceeded |
RATE_LIMITED | 429 | Too many requests |
Permissions
| Code | HTTP status | Message |
|---|---|---|
PERMISSION_INSUFFICIENT | 403 | Insufficient permissions |
PERMISSION_RESOURCE_NOT_FOUND | 404 | Resource not found |
PERMISSION_ACCESS_DENIED | 403 | Access to resource denied |
PERMISSION_OPERATION_NOT_ALLOWED | 403 | Operation not allowed |
PERMISSION_PROJECT_ACCESS_DENIED | 500 (default) | Project access denied |
PERMISSION_PIXEL_ACCESS_DENIED | 500 (default) | Pixel access denied |
PERMISSION_FORBIDDEN | 403 | Access denied |
PERMISSION_DENIED | 403 | Permission denied |
Network
| Code | HTTP status | Message |
|---|---|---|
NETWORK_CONNECTION_FAILED | 500 (default) | Connection failed |
NETWORK_TIMEOUT | 504 | Request timeout |
NETWORK_DNS_FAILED | 500 (default) | DNS resolution failed |
NETWORK_SSL_ERROR | 500 (default) | SSL/TLS error |
NETWORK_PROXY_ERROR | 500 (default) | Proxy error |
NETWORK_UPSTREAM_ERROR | 502 | Upstream service error |
Internal
| Code | HTTP status | Message |
|---|---|---|
INTERNAL_SERVER_ERROR | 500 | Internal server error |
INTERNAL_DATABASE_ERROR | 500 | Database error |
INTERNAL_CACHE_ERROR | 500 (default) | Cache error |
INTERNAL_CONFIGURATION_ERROR | 500 (default) | Configuration error |
INTERNAL_INITIALIZATION_ERROR | 503 | Initialization error |
INTERNAL_PROCESSING_ERROR | 500 | Processing error |
INTERNAL_UNKNOWN_ERROR | 500 (default) | An unknown error occurred |
SERVICE_UNAVAILABLE_TRANSIENT | 503 | A dependency is temporarily unavailable. Retry shortly. |
TRANSACTION_FAILED | 500 | The deletion failed because of a database error. Nothing was deleted. |
DELETE_FAILED | 500 | Failed to delete project |
PARTITION_RETIREMENT_IN_PROGRESS | 503 | The project data is being archived. Retry shortly. |
Session
| Code | HTTP status | Message |
|---|---|---|
SESSION_NOT_FOUND | 404 | Session not found |
SESSION_EXPIRED | 500 (default) | Session has expired |
SESSION_INVALID | 500 (default) | Session is invalid |
SESSION_CREATION_FAILED | 500 (default) | Failed to create session |
SESSION_UPDATE_FAILED | 500 (default) | Failed to update session |
SESSION_STORAGE_ERROR | 500 (default) | Session storage error |
SESSION_MAX_EXCEEDED | 500 (default) | Maximum sessions exceeded |
Pixel
| Code | HTTP status | Message |
|---|---|---|
PIXEL_NOT_FOUND | 404 | Pixel not found |
PIXEL_DISABLED | 500 (default) | Pixel is disabled |
PIXEL_CONFIGURATION_ERROR | 500 (default) | Pixel configuration error |
PIXEL_DOMAIN_NOT_ALLOWED | 500 (default) | Domain not allowed for this pixel |
PIXEL_PATH_SKIPPED | 500 (default) | Path is configured to be skipped |
PIXEL_EVENT_INVALID | 500 (default) | Invalid pixel event |
PIXEL_BATCH_TOO_LARGE | 413 | Event batch exceeds maximum size |
MISSING_PIXEL_ID | 400 | Project ID is required |
DETECTION_STORAGE_FAILED | 500 | Failed to store detection data |
PIXEL_CREATION_FAILED | 500 | Failed to create pixel for project |
API
| Code | HTTP status | Message |
|---|---|---|
API_ENDPOINT_NOT_FOUND | 404 | API endpoint not found |
API_METHOD_NOT_ALLOWED | 405 | HTTP method not allowed |
API_VERSION_NOT_SUPPORTED | 500 (default) | API version not supported |
API_CONTENT_TYPE_NOT_SUPPORTED | 415 | Content type not supported |
API_RESPONSE_TOO_LARGE | 500 (default) | Response exceeds maximum size |
API_REQUEST_TOO_LARGE | 413 | Request exceeds maximum size |
Billing
| Code | HTTP status | Message |
|---|---|---|
LIMIT_EXCEEDED | 402 | Billing limit exceeded |
BILLING_SUSPENDED | 402 | Account billing suspended |
BILLING_GRACE_PERIOD | 200 | Account in billing grace period |
Resources
| Code | HTTP status | Message |
|---|---|---|
CONFLICT | 409 | Resource conflict |
PROJECT_NOT_FOUND | 500 (default) | Project not found |
REVIEW_REQUIRED | 422 | Deploy requires explicit confirmation of the consequential writes it will perform. |
Policy
| Code | HTTP status | Message |
|---|---|---|
POLICY_FETCH_FAILED | 500 | Failed to fetch policy |
Analytics
| Code | HTTP status | Message |
|---|---|---|
INVALID_PERIOD | 400 | Period must be one of: hour, day, week, month |
ANALYTICS_FETCH_ERROR | 500 | Failed to retrieve analytics data |
STATS_FETCH_ERROR | 500 | Failed to retrieve stats |
Deploy
| Code | HTTP status | Message |
|---|---|---|
MISSING_USER_IDENTIFIER | 400 | Either userEmail or userGithubId is required to identify the user |
USER_NOT_FOUND | 404 | User not found in Checkpoint. The user must have an existing Checkpoint account to deploy. |
NO_ORGANIZATION | 400 | User has no organization in Checkpoint. Please complete onboarding first at https://kya.vouched.id |
DEPLOY_FAILED | 500 (default) | Deployment failed |
WFP_NOT_CONFIGURED | 500 (default) | Managed hosting is not configured |
NATIVE_ISSUER_PROVISIONING_BUSY | 500 (default) | Native issuer provisioning is busy or temporarily unavailable; retry deployment |
NATIVE_ISSUER_PROVISIONING_FAILED | 500 (default) | Native issuer provisioning failed; deployment retained for retry |
Un-prefixed
| Code | HTTP status | Message |
|---|---|---|
VALIDATION_ERROR | 400 | Invalid request data |
INTERNAL_ERROR | 500 | Internal server error |
INVALID_REQUEST | 400 | Invalid JSON body |
INVALID_JSON | 400 | Request body must be valid JSON |
INVALID_START_DATE | 400 | Invalid startDate format. Use ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ) |
INVALID_END_DATE | 400 | Invalid endDate format. Use ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ) |
INVALID_DATE_RANGE | 400 | startDate must be before endDate |
INVALID_DATE | 400 | Invalid date format. Use ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ) |
UNKNOWN_ERROR | 500 | Failed to delete project |
Lowercase (kya-os events wire format)
| Code | HTTP status | Message |
|---|---|---|
invalid_json | 400 | Request body must be valid JSON |
validation_error | 400 | Invalid request body |
Bouncer (lower-case wire format)
| Code | HTTP status | Message |
|---|---|---|
no_project | 400 | API key is not associated with a project |
missing_agent_did | 400 | agent_did query parameter is required |
not_configured | 400 | Bouncer is not configured for this project |
invalid_credential_config | 400 | Credential provider missing required fields: authEndpoint and responseFields |
project_not_found | 404 | Project not found |
project_mismatch | 403 | API key does not have access to this project |
missing_delegation_id | 400 | Delegation ID is required |
invalid_token | 401 | Invalid or expired delegation token |
delegation_mismatch | 403 | Delegation ID does not match token |
tokens_not_found | 404 | OAuth tokens not available for this delegation |
decryption_error | 500 | Failed to decrypt OAuth tokens |
no_proofs | 400 | At least one proof is required |
batch_too_large | 400 | Maximum batch size is 100 proofs |
no_proofs_processed | 400 | No proofs were processed. This indicates a server error. |
all_proofs_rejected | 400 | All proofs were rejected due to validation failures |
unauthorized | 401 | API key is not associated with a project |
forbidden | 403 | API key does not have access to this project |
not_found | 404 | Session not found |
config_not_found | 404 | Bouncer config not found for project |
agent_denied | 403 | Agent is on the deny list |
delegation_not_found | 404 | Delegation not found |
session_not_found | 404 | Session not found |
proof_validation_error | 400 | Proof validation failed |
insufficient_scopes | 403 | Missing required scopes |
delegation_validation_error | 400 | Delegation validation failed |
invalid_http_registration | 400 | Invalid or unsupported native HTTP registration |
authorization_host_unavailable | 503 | Authorization host is a project deployment that cannot currently serve consent |
Delegation OAuth (lower-case wire format)
| Code | HTTP status | Message |
|---|---|---|
invalid_request | 400 | Invalid request body |
unsupported_grant_type | 400 | Only authorization_code grant type is supported |
invalid_grant | 500 (default) | Invalid or expired authorization code |
invalid_delegation | 404 | Delegation not found or inactive |
internal_error | 500 | An internal error occurred during token exchange |
invalid_state | 400 | Restart authorization from the requesting agent. |
invalid_transaction | 400 | Restart authorization from the requesting agent. |
oauth_unavailable | 503 | OAuth is temporarily unavailable. Please request a new authorization link. |
oauth_not_configured | 400 | OAuth provider is not configured. Please configure OAuth in the dashboard. |
oauth_configuration_unsupported | 400 | The selected provider is not configured for the platform delegation callback. |
invalid_provider_config | 400 | OAuth provider is missing authorization endpoint |
rate_limit_exceeded | 429 | Too many requests. Please try again later. |
Bouncer (upper-case wire format)
| Code | HTTP status | Message |
|---|---|---|
INVALID_REQUEST_BODY | 400 | Invalid JSON in request body |
MCPI_CONFIG_NOT_FOUND | 404 | KYA-OS configuration not found |
CONSENT_CONFIG_NOT_FOUND | 404 | Consent configuration not found for this project |
PROJECT_LOOKUP_FAILED | 500 | Failed to lookup project |
CONFIG_VALIDATION_ERROR | 400 | Configuration validation failed |
CONFIG_FETCH_FAILED | 500 | Failed to fetch configuration |
CONFIG_UPDATE_FAILED | 500 | Failed to update configuration |
DEPLOYMENT_NOT_FOUND | 404 | No active deployment for this project |
INVALID_REQUEST_ID | 400 | Invalid delegation request ID format |
DELEGATION_REQUEST_NOT_FOUND | 404 | No delegation request exists for this ID. It may have expired, or it was never issued. |
Audit ingest
| Code | HTTP status | Message |
|---|---|---|
AUDIT_CREDENTIAL_REQUIRED | 401 | A source-bound audit ingest credential is required |
AUDIT_REQUEST_TOO_LARGE | 413 | Audit submission exceeds 6291456 bytes |
AUDIT_INVALID_JSON | 400 | Request body must be valid JSON |
AUDIT_INVALID_CREDENTIAL | 401 | Invalid audit ingest credential |
AUDIT_RATE_LIMITED | 429 | Audit ingest rate limit exceeded |
AUDIT_INVALID_SUBMISSION | 400 | Invalid audit recorder submission envelope |
AUDIT_INTERNAL_ERROR | 500 | Audit recorder is temporarily unavailable |
Audit protocol (relayed from @kya-os/mcp)
| Code | HTTP status | Message |
|---|---|---|
AUDIT_UNAUTHORIZED_SUBMISSION | 403 | Audit producer is not authorized for this ledger |
AUDIT_LEDGER_MISMATCH | 409 | Submission belongs to a different audit ledger than the credential binding |
AUDIT_EPOCH_MISMATCH | 409 | Submission belongs to a different ledger epoch |
AUDIT_EVENT_ID_CONFLICT | 409 | Producer event identity was reused with different content |
AUDIT_INVALID_EVENT | 422 | Audit event failed protocol validation |
AUDIT_EVIDENCE_FAILURE | 422 | Submitted evidence could not be matched or persisted |
AUDIT_EVIDENCE_INTEGRITY | 422 | Evidence ciphertext or metadata digest does not verify |
AUDIT_INVALID_CONFIGURATION | 503 | Audit recorder is temporarily unavailable |
AUDIT_JOURNAL_FAILURE | 503 | Audit recorder is temporarily unavailable |
AUDIT_APPEND_CONFLICT_EXHAUSTED | 503 | Audit recorder is temporarily unavailable |
AUDIT_EVIDENCE_LEGAL_HOLD | 500 | Audit recorder is temporarily unavailable |
AUDIT_EVIDENCE_ACCESS_DENIED | 500 | Audit recorder is temporarily unavailable |
AUDIT_CHECKPOINT_INVALID | 500 | Audit recorder is temporarily unavailable |
AUDIT_CHECKPOINT_ROLLBACK | 500 | Audit recorder is temporarily unavailable |
AUDIT_CHECKPOINT_CONFLICT | 500 | Audit recorder is temporarily unavailable |
AUDIT_CHECKPOINT_PUBLICATION_FAILED | 500 | Audit recorder is temporarily unavailable |
AUDIT_PROJECTION_CONFLICT | 500 | Audit recorder is temporarily unavailable |
AUDIT_MIRROR_VERIFICATION_FAILED | 500 | Audit recorder is temporarily unavailable |
AUDIT_MIRROR_CONTINUITY_FAILED | 500 | Audit recorder is temporarily unavailable |
AUDIT_MIRROR_OUT_OF_ORDER | 500 | Audit recorder is temporarily unavailable |
KYA-OS native HTTP protocol (kyaos/*)
| Code | HTTP status | Message |
|---|---|---|
kyaos/issuer-forbidden | 403 | The caller is not an authorized native issuer for this project |
kyaos/profile-violation | 500 (default) | The request does not conform to the KYA-OS native HTTP profile |
kyaos/invalid-session | 404 | The session is unknown, expired, or not owned by this project |
kyaos/session-conflict | 409 | The session is already bound to a different registration or grant |
kyaos/pickup-expired | 410 | The pickup anchor has expired |
kyaos/scope-insufficient | 403 | The requested scopes exceed what the session allows |
kyaos/consent-required | 403 | Consent terms must be accepted before a delegation can be issued |
kyaos/pickup-pinned | 403 | The pickup anchor is pinned to a different holder key |
kyaos/authorization-host-unavailable | 503 | The authorization host cannot currently serve this request |
kyaos/chain-broken | 403 | The propagation chain could not be verified |
kyaos/delegation-revoked | 403 | The delegation has been revoked |
kyaos/expired | 410 | The credential or proof has expired |
kyaos/holder-mismatch | 403 | The holder does not match the delegation or grant |
kyaos/invalid-signature | 403 | The signature could not be verified |
kyaos/session-mismatch | 409 | The session does not match the delegation or proof |
kyaos/policy-unavailable | 503 | The policy revision is currently unavailable |