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