Error Codes¶

Kiket surfaces structured error codes for API responses and sync jobs. Use this reference to diagnose issues quickly.

API Error Format¶

{
  "error": "validation_error",
  "message": "Transition not allowed",
  "code": "WORKFLOW_TRANSITION_GUARD_FAILED",
  "details": [
    {
      "field": "state",
      "message": "Transition from review to done requires approval"
    }
  ]
}

Simple errors return just error and optional message. Validation errors include a details array or errors array with field-level messages.

HTTP Status Codes¶

Status	Meaning	When
200	Success	GET, PATCH, POST (login, refresh)
201	Created	POST (register, create issue)
400	Bad Request	Missing required headers (X-Product-Slug)
401	Unauthorized	Invalid/expired token, wrong password
403	Forbidden	No permission, no subscription, feature disabled
404	Not Found	Resource doesn't exist or wrong organization
422	Unprocessable	Validation errors, blocked transitions
429	Too Many Requests	Rate limit exceeded
503	Service Unavailable	Billing not configured

Authentication Errors¶

Error	Status	Description	Resolution
`unauthorized`	401	Invalid email or password	Check credentials
`Token has expired`	401	Access token expired	Call `/auth/refresh` with refresh token
`Invalid token`	401	Malformed or tampered token	Re-authenticate
`Invalid token type`	401	Using refresh token as access token	Use the access_token for API calls
`Authorization header required`	401	Missing Bearer token	Add `Authorization: Bearer <token>` header
`No active subscription for this product`	403	Subscription canceled/expired	Redirect to billing
`Product context required`	400	Missing X-Product-Slug header	Add `X-Product-Slug` header
`Account has no organization`	422	User exists but has no org	Contact support

Billing Errors¶

Error	Status	Description
`Invalid plan tier`	422	Plan tier not in: solo, team, agency, enterprise
`Price not configured for this plan`	422	Stripe price ID not set in product feature_flags
`Billing not configured for this product`	503	No Stripe Connect account linked
`No billing account found`	404	No Stripe customer for this org
`Invalid payload`	400	Stripe webhook body not valid JSON
`Invalid signature`	400	Stripe webhook signature verification failed

Workflow Errors¶

Error	Status	Description
`state_required`	422	Transition request missing `state` parameter
`invalid_transition`	422	Transition not allowed (checklist, approval, guard, or invalid state)
`workflow_unavailable`	422	Project has no workflow defined

Validation Errors¶

{
  "errors": [
    "Title can't be blank",
    "Email is already registered",
    "Password is too short (minimum is 8 characters)"
  ]
}

Validation errors return an errors array with human-readable messages. When Accept-Language is set, messages are localized (Czech, German).

Compliance Report Errors¶

Error	Status	Description
`feature_not_enabled`	403	`blockchain_audit` feature not enabled
`insufficient_permissions`	403	User lacks admin/owner/compliance_officer role
`record_not_found`	404	Audit record doesn't exist in your organization
`anchor_not_found`	404	Blockchain anchor not found

Webhook Subscription Errors¶

Error	Status	Description
`Url must be a valid HTTP(S) URL`	422	Invalid webhook URL
`Events contain invalid event types`	422	Unknown event in events array

Rate Limiting¶

When rate limited, the response includes:

{
  "error": "usage_limit_exceeded",
  "message": "API request limit exceeded",
  "retry_after": 42
}

Headers on every response: - X-RateLimit-Limit — requests per window - X-RateLimit-Remaining — requests left - X-RateLimit-Reset — seconds until window resets

Sync Job Errors¶

sync.invalid_yaml — YAML parsing failed; check indentation and schema
sync.unauthorized — GitHub credentials invalid or missing scopes
sync.not_found — .kiket/ directory or files missing on the branch
sync.merge_conflict — Workflow cache update encountered conflicts; rerun after resolving

Localized Error Messages¶

Pass ?locale=cs or Accept-Language: cs to receive errors in Czech or German:

English	Czech	German
Invalid email or password	Neplatny e-mail nebo heslo	Ungultige E-Mail-Adresse oder Passwort
Token has expired	Platnost tokenu vyprsela	Token ist abgelaufen
No active subscription	Zadne aktivni predplatne	Kein aktives Abonnement
Resource not found	Zdroj nebyl nalezen	Ressource nicht gefunden