API Issues

This page covers common HTTP error responses from the LicenceForge REST API, their causes, and how to resolve them.

429 Too Many Requests

Symptom

API requests return HTTP 429 with a response body indicating the rate limit has been exceeded.

Cause

The client has exceeded the per-IP rate limit for the endpoint. LicenceForge enforces separate rate limits for validation and activation requests.

Solutions

1. Implement backoff in the client. The 429 response includes a Retry-After header indicating how many seconds the client should wait before retrying. Implement exponential backoff in your client library to respect this header.
2. Increase the rate limit. If legitimate usage exceeds the defaults, adjust the limits in LicenceForge > Settings or via WP-CLI:

   # Increase validation limit to 60 requests/minute
   wp option update wplf_rate_limit_validate 60
   
   # Increase activation limit to 20 requests/minute
   wp option update wplf_rate_limit_activate 20

3. Cache validation results client-side. Avoid calling the validation endpoint on every page load. Cache the result locally and re-validate periodically (e.g. once per day). The client library handles this automatically.

401 Unauthorized

Symptom

API requests return HTTP 401 with an error message indicating authentication failure.

Possible Causes

1. Missing API key header. The X-LicenceForge-Key header is not included in the request, and the wplf_require_api_key option is set to yes.
2. Invalid API key. The key provided does not match any record in the wplf_api_keys table (keys are stored as SHA-256 hashes).
3. Revoked API key. The key exists but has is_active = 0 (revoked).

Solutions

1. Ensure the request includes the API key header:

   curl -H "X-LicenceForge-Key: your-api-key-here" \
     https://your-site.com/wp-json/wplf/v1/licenses/validate

2. Verify the API key exists and is active in LicenceForge > API Keys. If the key was regenerated, update the client with the new value.
3. If the key was revoked, create a new one with the appropriate permissions. See API Keys.

403 Forbidden

Symptom

API requests return HTTP 403 indicating the authenticated user or API key does not have sufficient permissions.

Possible Causes

1. Insufficient API key permissions. A key with read permissions cannot perform write operations (creating licenses, activating, etc.). Permission levels are hierarchical: read < write < admin.
2. WordPress user lacks capabilities. If using cookie-based authentication (admin panel AJAX), the logged-in WordPress user must have the manage_options capability for admin-level API operations.

Solutions

1. Check the API key's permission level in LicenceForge > API Keys. Upgrade the permission level if the key needs to perform write or admin operations:

   Permission	Allowed Operations
   read	Validate licenses, check update info
   write	All read operations + activate, deactivate
   admin	All operations including create, delete, and manage

2. For cookie-authenticated requests, verify the WordPress user's role includes the manage_options capability (typically Administrator role).

404 Not Found

Symptom

API requests return HTTP 404.

Possible Causes

1. WordPress REST API is disabled. A security plugin or custom code has disabled the REST API entirely.
2. Incorrect endpoint path. The URL does not match any registered LicenceForge route.
3. Product slug does not exist. An endpoint that requires a product slug was called with a slug that does not match any product in the database.
4. Permalink structure not configured. WordPress pretty permalinks are required for the REST API to work. The default "Plain" setting does not support REST routes.

Solutions

1. Verify the REST API is accessible:

   curl https://your-site.com/wp-json/wplf/v1/

   If this returns a 404 or empty response, the REST API may be disabled.

2. Check the endpoint path against the Public Endpoints or Admin Endpoints documentation.
3. Verify the product slug exists in LicenceForge > Products.
4. Ensure WordPress permalinks are set to anything other than "Plain" in Settings > Permalinks. After changing, flush rewrite rules:

   wp rewrite flush

CORS Issues

Symptom

Browser-based API requests fail with CORS (Cross-Origin Resource Sharing) errors in the console, such as Access-Control-Allow-Origin header missing.

Cause

WordPress does not add CORS headers to REST API responses by default. If your client application runs in a browser on a different domain than your WordPress site, the browser blocks the response.

Solution

Add a rest_api_init filter in your theme's functions.php or a custom plugin to set the required CORS headers:

add_action( 'rest_api_init', function () {
    remove_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' );
    add_filter( 'rest_pre_serve_request', function ( $value ) {
        header( 'Access-Control-Allow-Origin: https://your-app-domain.com' );
        header( 'Access-Control-Allow-Methods: GET, POST, OPTIONS' );
        header( 'Access-Control-Allow-Headers: X-LicenceForge-Key, Content-Type' );
        return $value;
    });
}, 15 );

Quick Reference

Related Pages

• Public Endpoints — Full endpoint reference
• Admin Endpoints — Administrative API operations
• API Keys — Key management and permissions
• Rate Limiting — Rate limit configuration and behavior
• Debug Mode — Enabling detailed logging for diagnosis