Skip to content
HeadlessWP Pro

Troubleshooting

Practical debugging steps, self-test pointers, and what to capture.

Troubleshooting and self-test

This playbook helps you move from symptom to root cause quickly.

Always capture

Before you escalate, capture these details:

  • Route and method
  • Full HTTP status
  • meta.correlationId (or X-Correlation-Id response header)
  • Auth mode used (cookie, Bearer, or API key)
  • Whether the request came from a browser (CORS/nonce checks apply)

First checks (90 seconds)

Run these checks in order:

  1. GET /wp-json/headlesswp/v1/health
  2. GET /wp-json/headlesswp/v1/config/app
  3. GET /wp-json/headlesswp/v1/nonce

If any of these fail, fix routing/platform basics first (permalinks, REST availability, SSL, and cache layers).

Common failures by status

401 (authentication)

Most common cause: missing, invalid, or expired credentials.

Check:

  • Cookie auth: login succeeded and session cookies are present/sent
  • Bearer auth: Authorization: Bearer <token> is present and valid
  • API key auth: Authorization: HeadlessWPProKey <token> is present and valid
  • Endpoint actually requires auth for that method

403 (forbidden)

A 403 usually means policy denial, not malformed JSON.

Check for common cases:

  • CSRF_FAILED: cookie/session flow missing X-WP-Nonce on a mutation
  • SERVICE_ACCOUNT_SCOPE_DENIED: API key exists but required scope is missing
  • TOKEN_AUTH_DISABLED or API_KEY_AUTH_DISABLED: header sent for a disabled auth mode
  • Browser-blocked CORS request before WordPress receives it

413 (REQUEST_TOO_LARGE)

Payload exceeded configured request size limits.

Check:

  • Payload size vs configured cap
  • Whether large binary/blob data should use an upload-specific flow instead of JSON

429 (RATE_LIMITED)

Retry loops or bursty clients can trip endpoint rate limits.

Check:

  • Client retry behavior includes backoff and jitter
  • No accidental infinite retry integration
  • Bucket sizing is appropriate for legitimate traffic

422 (validation)

Request body shape does not satisfy endpoint schema.

Check:

  • Content-Type: application/json for JSON requests
  • Field-level details in the error payload
  • Request shape against endpoint docs before retrying

CORS checklist

For browser-originated issues:

  • Request Origin exactly matches a configured allowed origin
  • Preflight (OPTIONS) includes expected Access-Control-* response headers
  • Site/app protocol mismatch (http vs https) is not causing browser policy failures
  • Cookie-based calls use fetch(..., { credentials: "include" }) and compatible cookie policy

Nonce checklist

For cookie/session auth flows:

  1. Login first (session cookies must be present)
  2. Call GET /wp-json/headlesswp/v1/nonce
  3. Send X-WP-Nonce for state-changing calls (POST, PATCH, DELETE)

If you are using API keys, nonce is not the mechanism. Verify auth mode selection and avoid mixing modes.

Self Test and Environment page

Use Admin → Self Test & Environment to validate environment wiring:

  • Enabled/disabled auth modes
  • Provider/dependency readiness
  • Payment/webhook prerequisites (if relevant)
  • Required database tables for logs/events/metrics

Use export/import to replicate known-good configuration between environments.

What to include in a support ticket

Site URL:
Environment: local / staging / production
Endpoint + method:
HTTP status:
Correlation ID:
Auth mode: cookie / bearer / api key
Request headers (redact secrets):
Request body (redact secrets):
Self Test export (if config-related):