Error Code Reference

Use this guide for quick handling of common API error codes.

Common codes

Code	Typical status	Meaning	Action
`missing_bearer_token`	401	Missing `Authorization` header	Send JWT/PAT bearer token
`invalid_token`	401	Token malformed or invalid	Regenerate token and retry
`token_expired`	401	JWT/PAT expired	Refresh/login and retry
`insufficient_scope`	403	PAT lacks required scope	Mint PAT with required scopes
`insufficient_role`	403	Caller role not authorized	Use owner/operator credential
`feature_locked`	403	Feature not available on current plan	Upgrade plan or disable flow
`invalid_payload`	400	Request body shape/fields invalid	Fix request payload
`validation_error`	400	Validation failed	Correct inputs and retry
`not_found`	404	Target resource does not exist	Verify IDs/slugs/handle
`conflict`	409	State conflict or duplicate	Read current state, then retry with corrected action
`rate_limited`	429	Request rate exceeded	Backoff and honor `Retry-After`
`internal_error`	500	Unexpected server failure	Retry with exponential backoff
`knowledge_unavailable`	503	Knowledge subsystem not available	Retry later; alert operator if sustained
`domain_purchase_deprecated`	400	Platform domain purchase removed	Use BYO domain flow

Handling policy

Retry only for transient classes (429, 5xx, temporary 503).
Do not retry deterministic client failures (400, 401, 403, 404, 409) without changing input/auth/state.
Log both HTTP status and error.code for incident triage.

Full inventory

This public reference covers the external API error classes required for integrator workflows. For unresolved cases, escalate with Troubleshooting and Support and include request IDs plus payload context.

Updated Jun 19, 2026