Error Codes

This page provides a complete reference for all error codes returned by the Web3.Market License API, along with the HTTP status codes and response formats used across all endpoints.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable description of the error."
}

For verification endpoints (/verify), the format uses valid instead of success:

{
  "valid": false,
  "error": "error_code"
}

Error Code Reference

Error Code	HTTP Status	Description	Returned By
`invalid_key`	`404`	The provided license key does not exist in the system.	`/activate`, `/verify`, `/deactivate`, `/status`
`invalid_domain`	`200`	The domain is not activated on this license key.	`/verify`
`suspended`	`422`	The license has been temporarily suspended by the seller or platform.	`/activate`, `/verify`
`revoked`	`422`	The license has been permanently revoked and cannot be reactivated.	`/activate`, `/verify`
`expired`	`422`	The license has passed its expiration date.	`/activate`, `/verify`
`domain_limit_reached`	`422`	The license has reached its maximum number of activated domains.	`/activate`
`domain_not_found`	`422`	The specified domain is not activated on this license (deactivation target).	`/deactivate`

HTTP Status Codes

The License API uses the following HTTP status codes:

200 OK

The request was processed successfully. For verification endpoints, a 200 response does not necessarily mean the license is valid — check the valid field in the response body.

// Successful verification
{ "valid": true, "license": { "expires_at": null } }
 
// Failed verification (still 200)
{ "valid": false, "error": "invalid_domain" }
 
// Successful activation
{ "success": true, "message": "License activated successfully on domain.", ... }

404 Not Found

The license key does not exist. This is returned when the license_key parameter does not match any record in the system.

{
  "success": false,
  "error": "invalid_key",
  "message": "The provided license key does not exist."
}

422 Unprocessable Entity

The request was well-formed but the operation cannot be completed due to a business logic constraint (e.g., license is suspended, domain limit reached).

{
  "success": false,
  "error": "domain_limit_reached",
  "message": "This license has reached its maximum number of activated domains."
}

429 Too Many Requests

You have exceeded the rate limit for the endpoint. See Rate Limits for per-endpoint limits.

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later."
}

The response includes headers to help you manage rate limiting:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 45

Error Handling Best Practices

Always check the error field programmatically rather than parsing the message string. Error messages are human-readable and may change. Error codes are stable and will not change without a major version bump.

Recommended Error Handling

const response = await fetch(
  `https://verify.web3.market/verify?license_key=${key}&domain=${domain}`
);
const data = await response.json();
 
if (data.valid) {
  // License is valid — proceed normally
  return;
}
 
switch (data.error) {
  case 'invalid_key':
    // The license key is wrong — prompt user to check their key
    break;
  case 'invalid_domain':
    // The domain is not activated — prompt user to activate
    break;
  case 'expired':
    // License has expired — prompt user to renew
    break;
  case 'suspended':
    // License temporarily suspended — contact seller
    break;
  case 'revoked':
    // License permanently revoked — contact support
    break;
  default:
    // Unknown error — log and handle gracefully
    break;
}

Handling Rate Limits

If you receive a 429 response, wait for the duration specified in the Retry-After header before retrying:

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10);
  console.warn(`Rate limited. Retrying in ${retryAfter} seconds.`);
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // Retry the request
}

Webhooks Rate Limits