Error Codes — Tierux Docs

Error response format

All Tierux API errors follow this structure:

// Error response
{
  "ok": false,
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}

HTTP status codes are used appropriately: 400 for client errors, 401 for authentication, 404 for not found, 500 for server errors.

Authentication errors

UNAUTHORIZED (401)
→ API key missing or invalid. Check your Authorization header.

FORBIDDEN (403)
→ Valid key, but insufficient permissions for this resource.

INVALID_API_KEY (401)
→ API key format is invalid (must be pe_live_… prefix).

Verification errors

INVALID_TOKEN (400)
→ The purchase token failed store verification.
   Possible: token expired, revoked, or from different app.

TOKEN_ALREADY_VERIFIED (409)
→ This purchase token was already verified. The existing
   entitlement state is returned in the response body.

INVALID_REQUEST (400)
→ Required fields missing (appId, userId, productId, etc.)
   or JSON body is malformed.
   Also returned when userId, productId, or entitlementId contain
   characters outside [A-Za-z0-9._:-] — these are opaque keys, so
   emails or any value with '/', '@', or spaces are rejected. Use a
   Firebase uid or a random customer key.

APP_NOT_FOUND (404)
→ The specified appId does not exist in this project.

PRODUCT_NOT_MAPPED (400)
→ The productId has no entitlement mapping configured.
   Map products via MCP or dashboard before verifying.

Entitlement errors

ENTITLEMENT_NOT_FOUND (404)
→ No entitlement record for this userId + entitlement.
   This is normal for users who have never purchased.

USER_NOT_FOUND (404)
→ This userId has no entitlements at all in this project.

ENTITLEMENT_EXPIRED (200 — not an error)
→ The entitlement exists but has expired. active = false.

Webhook and server errors

WEBHOOK_VALIDATION_FAILED (400)
→ Incoming webhook JWT signature or audience validation failed.

INTERNAL_ERROR (500)
→ Unexpected server error. Tierux logs the full details.
   If persistent, check the status page or contact support.

RATE_LIMITED (429)
→ Too many requests. Retry after the Retry-After header value.

Google Play specific errors

PLAY_API_ERROR (502)
→ Google Play Developer API returned an error.
   Check that your Google Play service account is valid.

PLAY_QUOTA_EXCEEDED (429)
→ Google Play API quota exceeded. Tierux retries with
   exponential backoff; if persistent, contact support.

Related docs

Docs: Tokens

How Tierux handles purchase tokens — hashing, encryption, and verification.

Docs: Webhooks

Webhook configuration — RTDN, App Store Notifications, and event handling.

Quickstart

Checklist for Tierux configuration, required store-console work, REST integration, and purchase verification.