API Error Codes

Reference for all error responses from the Gravity Licensing API.

Overview

All API errors follow a consistent JSON format:

{
  "error": {
    "code": "LICENSE_EXPIRED",
    "message": "Your license has expired. Please renew to continue.",
    "details": {}
  }
}

License Verification Errors (POST /api/license/verify)

HTTPCodeMessageAction
400INVALID_KEYInvalid license key formatPrompt user for valid key
404KEY_NOT_FOUNDLicense key not foundPrompt user for valid key
403KEY_REVOKEDLicense has been revokedLock Pro features, show support link
403LICENSE_EXPIREDLicense expired on {date}Prompt renewal
403MACHINE_LIMIT_EXCEEDEDMaximum machines ({n}) reachedShow machine management UI
403MACHINE_REVOKEDThis machine has been revokedLock Pro features, show support link
429RATE_LIMITEDToo many verification attemptsExponential backoff, retry after Retry-After
200VALID (valid:false)Grace period activeAllow offline use, warn user

Auth/Login Errors (POST /api/auth/login)

HTTPCodeMessageAction
400INVALID_CREDENTIALSInvalid email or passwordShow login error
401UNAUTHORIZEDSession invalid or expiredClear token, force re-login
402PAYMENT_REQUIREDLicense expired or no active subscriptionRedirect to billing
403MACHINE_NOT_ACTIVATEDMachine not linked to licenseRun license verification first
429RATE_LIMITEDToo many login attemptsExponential backoff

Heartbeat Errors (POST /api/auth/heartbeat)

HTTPCodeMessageAction
401SESSION_EXPIREDSession token expiredForce re-login
403LICENSE_REVOKEDLicense revoked since last heartbeatLock Pro features immediately
403MACHINE_REVOKEDThis machine revokedLock Pro features immediately
403PLAN_DOWNGRADEDLicense downgraded to FreeLock Pro features
429RATE_LIMITEDHeartbeats too frequentRespect Retry-After header