13 structured token errors
Errors
Diagnose merchant-token failures by separating credential validity, route policy, merchant state, resource ownership, and lifecycle conflicts.
Structured response shape
Authentication and token-management errors use structured Nest responses with a machine-readable code and a human-readable message.
{
"code": "API_TOKEN_INVALID",
"message": "Invalid API token."
}Do not parse message text for control flow. Branch on the HTTP status and stable code.
Start with the status family
Re-authenticate or replace
The bearer credential is invalid or inactive. Stop blind retries and inspect format, version, expiry, revocation, and live owner state.
Change policy, not the token string
The credential may be valid, but the route, scope, merchant state, or existing permission denies the action.
Resolve lifecycle state
The action conflicts with capacity, naming, editability, or deletion rules. Fetch fresh token metadata before retrying.
Error catalog
API_TOKEN_INVALIDMalformed, unknown, wrong-version, or otherwise invalid token.
API_TOKEN_INACTIVERevoked or expired token, missing owner, suspended owner, role changed, or invalidated ownership.
API_TOKEN_SCOPE_REQUIREDThe token is valid but lacks the handler's required scope.
API_TOKEN_ROUTE_NOT_ALLOWEDAPI tokens are not enabled for the handler or the route is explicitly denied.
API_TOKEN_MERCHANT_INACTIVEThe bound merchant is missing or no longer active.
API_TOKEN_LIMIT_REACHEDAll five merchant token slots are occupied.
API_TOKEN_NAME_EXISTSThe name already exists for the merchant, case-insensitively.
API_TOKEN_NOT_FOUNDThe token ID is invalid or not owned by the authenticated merchant.
API_TOKEN_NOT_EDITABLEThe token is revoked, expired, or became inactive during update or rotation.
API_TOKEN_DELETE_REQUIRES_INACTIVEAn active unexpired token must be revoked before deletion.
API_TOKEN_INVALID_SCOPESScopes are empty, duplicated, unknown, or unsupported.
API_TOKEN_INVALID_EXPIRYExpiration is invalid or less than 24 hours in the future.
API_TOKEN_INVALID_NAMEThe name is empty or exceeds 64 characters.
Production handling guidance
Log the code, status, route template, token record ID if already known, and correlation metadata—never the bearer value.
For scope or lifecycle conflicts, load current token metadata with an interactive JWT instead of inferring state from an old cache.
Do not indefinitely retry invalid credentials. Retry transient transport failures separately from deterministic 401/403/409 responses.
Unknown, expired, and revoked credentials intentionally avoid revealing whether a secret previously existed.