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_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

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

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.

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
`INVALID_EDGE_SIGNATURE`	403	Invalid request signature
`DETECTION_STORAGE_FAILED`	500	Failed to store detection data

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

Un-prefixed

Code	HTTP status	Message
`VALIDATION_ERROR`	400	Invalid request data
`INTERNAL_ERROR`	500	Internal server error

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

Error Codes