Skip to content
HeadlessWP Pro

Error codes

How to interpret error codes, statuses, and next steps.

Error codes and statuses

Use this reference to map HTTP status + error.code to likely root cause and next step.

Common HTTP statuses used

  • 200 OK: request succeeded
  • 400 Bad Request: malformed input (less common than 422)
  • 401 Unauthorized: missing/invalid authentication
  • 403 Forbidden: policy denial (scope, CSRF, CORS, feature disabled)
  • 404 Not Found: route/resource missing (or disabled extension)
  • 409 Conflict: idempotency/state conflict
  • 413 Payload Too Large: request exceeded configured size limit
  • 422 Unprocessable Entity: validation failure
  • 429 Too Many Requests: rate limit exceeded
  • 500 Internal Server Error: server exception
  • 501 Not Implemented: provider/strategy is a stub or unavailable
  • 503 Service Unavailable: dependency/provider outage

How to debug any error quickly

Capture:

  • Endpoint + method
  • HTTP status
  • error.code + error.message
  • meta.correlationId (or X-Correlation-Id header)
  • Auth mode used (cookie, Bearer, API key)

Then:

  1. Search logs/security events by correlation id.
  2. Validate CORS + nonce expectations for browser/cookie flows.
  3. Validate API key scopes for service-account flows.

Quick map by error family

  • Auth / identity (401/403)
    • NOT_AUTHENTICATED, AUTH_INVALID_CREDENTIALS, INVALID_TOKEN
    • TOKEN_AUTH_DISABLED, API_KEY_AUTH_DISABLED, SERVICE_ACCOUNT_SCOPE_DENIED
  • Browser/policy (403 or browser-blocked)
    • CSRF_FAILED, CORS blocks, SUSPICIOUS_REQUEST_*
  • Feature/provider/dependency (403/501/503)
    • FEATURE_DISABLED, DEPENDENCY_UNAVAILABLE, STORE_API_*, CHECKOUT_*
  • Validation/input (413/415/422)
    • VALIDATION_FAILED, PASSWORD_POLICY_VIOLATION, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE
  • Not found (404)
    • NOT_FOUND, *_NOT_FOUND (product, form, booking, user, page, menu)
  • Conflict (409)
    • IDEMPOTENCY_KEY_REUSE_CONFLICT

Known error codes (observed in code)

  • ACCOUNT_DEACTIVATION_DISABLED
  • ACCOUNT_EXISTS_LOGIN_REQUIRED
  • AFFILIATE_EXISTS
  • AFFILIATE_NOT_ACTIVE
  • AFFILIATE_NOT_FOUND
  • AFFILIATE_TERMS_DISABLED
  • AFFILIATE_TERMS_REQUIRED
  • ALERT_NOT_DISMISSIBLE
  • API_KEY_AUTH_DISABLED
  • APPLICATION_FAILED
  • AUTH_ACCOUNT_DEACTIVATED
  • AUTH_EMAIL_VERIFICATION_TOKEN_ALREADY_USED
  • AUTH_EMAIL_VERIFICATION_TOKEN_EXPIRED
  • AUTH_EMAIL_VERIFICATION_TOKEN_INVALID
  • AUTH_INVALID_CREDENTIALS
  • AUTH_PASSWORD_RESET_DISABLED
  • AUTH_PASSWORD_RESET_FAILED
  • AUTH_PASSWORD_RESET_TOKEN_EXPIRED
  • AUTH_PASSWORD_RESET_TOKEN_INVALID
  • AUTH_PASSWORD_SET_DISABLED
  • AUTH_RATE_LIMITED
  • AUTH_REGISTRATION_DISABLED
  • AUTH_REGISTRATION_FAILED
  • BILLING_NOT_ENABLED
  • BILLING_PORTAL_UNAVAILABLE
  • BOOKING_ACTION_FAILED
  • BOOKING_ACTION_NOT_ALLOWED
  • BOOKING_ALREADY_CANCELLED
  • BOOKING_CANCEL_NOT_ALLOWED
  • BOOKING_CREATE_FAILED
  • BOOKING_NOT_FOUND
  • BOOKING_RESCHEDULE_NOT_ALLOWED
  • BOOKING_SLOT_UNAVAILABLE
  • BOOKING_TYPE_NOT_FOUND
  • CHECKOUT_DISABLED
  • CHECKOUT_EMAIL_INVALID
  • CHECKOUT_EMAIL_REQUIRED
  • CHECKOUT_FAILED
  • CHECKOUT_NOT_IMPLEMENTED
  • CHECKOUT_USER_CREATE_FAILED
  • COUPON_APPLY_RATE_LIMITED
  • COUPON_CODE_INVALID
  • COUPON_CODE_REQUIRED
  • COUPON_PROBE_LIMITED
  • COURSE_NOT_FOUND
  • CSRF_FAILED
  • DEPENDENCY_UNAVAILABLE
  • DONATION_NOT_FOUND
  • FEATURE_DISABLED
  • FORBIDDEN
  • FORM_NOT_FOUND
  • IDEMPOTENCY_KEY_REUSE_CONFLICT
  • INTERNAL_SERVER_ERROR
  • INVALID_TOKEN
  • INVALID_WEBHOOK_PAYLOAD
  • LICENSE_REQUIRED
  • LOG_NOT_FOUND
  • MEDIA_DOWNLOADS_DISABLED
  • MEDIA_DOWNLOAD_FORBIDDEN
  • MEDIA_RESOURCE_NOT_FOUND
  • MENU_NOT_FOUND
  • NOT_AUTHENTICATED
  • NOT_FOUND
  • PAGE_NOT_FOUND
  • PASSWORD_POLICY_VIOLATION
  • PAYLOAD_TOO_LARGE
  • PRODUCT_NOT_ALLOWED
  • PRODUCT_NOT_FOUND
  • PROFILE_UPDATE_FAILED
  • PURCHASE_NOT_FOUND
  • RATE_LIMITED
  • SERVICE_ACCOUNT_SCOPE_DENIED
  • SSO_ASSERTION_INVALID
  • SSO_DISABLED
  • SSO_PROVIDER_NOT_CONFIGURED
  • STORE_API_PROXY_ERROR
  • STORE_API_UNAVAILABLE
  • STORE_API_UPSTREAM_ERROR
  • SUSPICIOUS_REQUEST_BLOCKED
  • SUSPICIOUS_REQUEST_THROTTLED
  • UNKNOWN_ERROR
  • UNSUPPORTED_MEDIA_TYPE
  • USER_NOT_FOUND
  • VALIDATION_FAILED
  • WEBHOOK_NOT_CONFIGURED

Error envelope shape

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed.",
    "details": {},
    "httpStatus": 422,
    "correlationId": "abcd1234",
    "hints": []
  },
  "meta": {}
}