Error Codes

Complete reference of 40 error codes across 11 categories returned by the Subscriptions Service.

Error response formatjson

{
  "error": {
    "code": "ERR_SUBSCRIPTIONS_SUBSCRIPTION_NOT_FOUND",
    "message": "Subscription with ID abc-123 not found",
    "http": 404
  }
}

Subscription7 errors

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_SUBSCRIPTION_NOT_FOUND`	404	`SUBSCRIPTION_NOT_FOUND`	Subscription not found	Verify the subscription ID exists for this tenant
`ERR_SUBSCRIPTIONS_SUBSCRIPTION_ALREADY_EXISTS`	409	`SUBSCRIPTION_ALREADY_EXISTS`	Active subscription already exists for this actor	Check if actor already has an active subscription
`ERR_SUBSCRIPTIONS_SUBSCRIPTION_INVALID_STATE`	400	`SUBSCRIPTION_INVALID_STATE`	Subscription is in an invalid state for this operation	Check subscription status before performing the operation
`ERR_SUBSCRIPTIONS_SUBSCRIPTION_CANNOT_UPGRADE`	400	`SUBSCRIPTION_CANNOT_UPGRADE`	Subscription cannot be upgraded	Target plan must be a higher tier and subscription must be active
`ERR_SUBSCRIPTIONS_SUBSCRIPTION_CANNOT_DOWNGRADE`	400	`SUBSCRIPTION_CANNOT_DOWNGRADE`	Subscription cannot be downgraded	Target plan must be a lower tier and subscription must be active
`ERR_SUBSCRIPTIONS_SUBSCRIPTION_ALREADY_CANCELLED`	400	`SUBSCRIPTION_ALREADY_CANCELLED`	Subscription is already cancelled	Cannot cancel a subscription that is already cancelled
`ERR_SUBSCRIPTIONS_SUBSCRIPTION_NOT_ACTIVE`	400	`SUBSCRIPTION_NOT_ACTIVE`	Subscription is not active	Operation requires an active subscription

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_PLAN_NOT_FOUND`	404	`PLAN_NOT_FOUND`	Plan not found	Verify the plan ID exists
`ERR_SUBSCRIPTIONS_PLAN_INACTIVE`	400	`PLAN_INACTIVE`	Plan is not active	Cannot subscribe to a deactivated plan
`ERR_SUBSCRIPTIONS_PLAN_INVALID_TIER`	400	`PLAN_INVALID_TIER`	Invalid plan tier	Use a valid SubscriptionTier value

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_QUOTA_NOT_FOUND`	404	`QUOTA_NOT_FOUND`	Quota not found	Verify quota exists for this subscription/feature
`ERR_SUBSCRIPTIONS_QUOTA_EXCEEDED`	403	`QUOTA_EXCEEDED`	Quota has been exceeded	Upgrade subscription or wait for quota reset
`ERR_SUBSCRIPTIONS_QUOTA_LIMIT_REACHED`	403	`QUOTA_LIMIT_REACHED`	Quota limit reached (100% utilization)	Upgrade subscription tier for higher limits

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_INVOICE_NOT_FOUND`	404	`INVOICE_NOT_FOUND`	Invoice not found	Verify the invoice ID exists
`ERR_SUBSCRIPTIONS_INVOICE_ALREADY_PAID`	400	`INVOICE_ALREADY_PAID`	Invoice has already been paid	Cannot pay an invoice that is already in paid status
`ERR_SUBSCRIPTIONS_INVOICE_GENERATION_FAILED`	500	`INVOICE_GENERATION_FAILED`	Failed to generate invoice	Internal error; retry or contact support

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_PAYMENT_FAILED`	402	`PAYMENT_FAILED`	Payment processing failed	Check payment method and retry
`ERR_SUBSCRIPTIONS_PAYMENT_METHOD_REQUIRED`	400	`PAYMENT_METHOD_REQUIRED`	Payment method is required	Add a payment method before subscribing
`ERR_SUBSCRIPTIONS_PAYMENT_INSUFFICIENT_FUNDS`	402	`PAYMENT_INSUFFICIENT_FUNDS`	Insufficient funds	Ensure sufficient balance and retry

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_TRIAL_NOT_FOUND`	404	`TRIAL_NOT_FOUND`	Trial not found	Verify the trial ID exists
`ERR_SUBSCRIPTIONS_TRIAL_ALREADY_EXISTS`	409	`TRIAL_ALREADY_EXISTS`	Trial already exists for this actor	Actor already has an active trial
`ERR_SUBSCRIPTIONS_TRIAL_EXPIRED`	400	`TRIAL_EXPIRED`	Trial has expired	Trial period has ended; subscribe to continue
`ERR_SUBSCRIPTIONS_TRIAL_CANNOT_EXTEND`	400	`TRIAL_CANNOT_EXTEND`	Trial cannot be extended	Trial is at max duration or extension not allowed

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_STUDENT_ENROLLMENT_NOT_FOUND`	404	`STUDENT_ENROLLMENT_NOT_FOUND`	Student enrollment not found	Verify enrollment exists
`ERR_SUBSCRIPTIONS_STUDENT_ENROLLMENT_ALREADY_EXISTS`	409	`STUDENT_ENROLLMENT_ALREADY_EXISTS`	Student enrollment already exists	Actor is already enrolled in student program
`ERR_SUBSCRIPTIONS_STARTUP_APPLICATION_NOT_FOUND`	404	`STARTUP_APPLICATION_NOT_FOUND`	Startup application not found	Verify the application ID exists
`ERR_SUBSCRIPTIONS_STARTUP_APPLICATION_ALREADY_EXISTS`	409	`STARTUP_APPLICATION_ALREADY_EXISTS`	Startup application already exists	Application was already submitted

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_DISCOUNT_NOT_FOUND`	404	`DISCOUNT_NOT_FOUND`	Discount not found	Verify the discount ID exists
`ERR_SUBSCRIPTIONS_DISCOUNT_CODE_ALREADY_EXISTS`	409	`DISCOUNT_CODE_ALREADY_EXISTS`	Discount code already exists	Use a different discount code
`ERR_SUBSCRIPTIONS_DISCOUNT_EXPIRED`	400	`DISCOUNT_EXPIRED`	Discount has expired	Discount is past its validUntil date
`ERR_SUBSCRIPTIONS_DISCOUNT_MAX_USES_REACHED`	400	`DISCOUNT_MAX_USES_REACHED`	Discount max uses reached	Discount has been used the maximum number of times
`ERR_SUBSCRIPTIONS_DISCOUNT_NOT_APPLICABLE`	400	`DISCOUNT_NOT_APPLICABLE`	Discount not applicable to this plan	Check applicablePlans for this discount
`ERR_SUBSCRIPTIONS_DISCOUNT_INVALID_CODE`	400	`DISCOUNT_INVALID_CODE`	Invalid discount code	Code does not exist or is inactive

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_REFERRAL_NOT_FOUND`	404	`REFERRAL_NOT_FOUND`	Referral not found	Referral code lookup failed
`ERR_SUBSCRIPTIONS_REFERRAL_CODE_INVALID`	400	`REFERRAL_CODE_INVALID`	Referral code is invalid	Check code format and existence
`ERR_SUBSCRIPTIONS_REFERRAL_ALREADY_USED`	400	`REFERRAL_ALREADY_USED`	Referral code has already been used	Code was already redeemed

Code	HTTP	Name	Description	Resolution
`ERR_SUBSCRIPTIONS_INVALID_ACTOR_TYPE`	400	`INVALID_ACTOR_TYPE`	Invalid actor type	Actor type must be "user" or "team"
`ERR_SUBSCRIPTIONS_INVALID_BILLING_CYCLE`	400	`INVALID_BILLING_CYCLE`	Invalid billing cycle	Billing cycle must be "monthly" or "annually"
`ERR_SUBSCRIPTIONS_INVALID_TENANT_ID`	400	`INVALID_TENANT_ID`	Invalid tenant ID	Tenant ID must be a valid UUID

Code	HTTP	Name	Description	Resolution
`Unauthorized`	401	`UNAUTHORIZED`	Missing or invalid JWT token	Provide a valid JWT Bearer token
`Internal API key not configured`	401	`INTERNAL_KEY_NOT_CONFIGURED`	INTERNAL_API_KEY env var not set (fail-closed)	Configure the INTERNAL_API_KEY environment variable
`Invalid internal API key`	401	`INVALID_INTERNAL_KEY`	Wrong x-internal-api-key header value	Use the correct internal API key
`Forbidden resource`	403	`FORBIDDEN`	Insufficient role for this endpoint	Request required role from admin