Error Codes

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

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error."
  }
}

Error Code Reference

Error Code	HTTP Status	Description
`UNAUTHORIZED`	`401`	The API key is missing, invalid, or expired.
`RATE_LIMITED`	`429`	You have exceeded the rate limit for your tier.
`NOT_FOUND`	`404`	The requested resource does not exist.
`NOT_PURCHASED`	`403`	The user has not purchased the requested template or product.
`PURCHASE_CHECK_FAILED`	`503`	The purchase verification service is temporarily unavailable.
`VALIDATION_ERROR`	`422`	The request body failed validation (missing or invalid fields).

HTTP Status Codes

The Web3.Market API uses the following HTTP status codes:

200 OK

The request was processed successfully.

{
  "templates": [...]
}

401 Unauthorized

The API key is missing, invalid, or expired. Include a valid API key in the X-API-Key header.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key."
  }
}

403 Forbidden

The request is authenticated but the user does not have permission. This is returned when accessing a resource that requires a purchase or a higher tier.

{
  "error": {
    "code": "NOT_PURCHASED",
    "message": "You must purchase this template before downloading."
  }
}

404 Not Found

The requested resource does not exist.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Template not found."
  }
}

422 Unprocessable Entity

The request body failed validation. The response includes details about which fields are invalid.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The title field is required."
  }
}

429 Too Many Requests

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

{
  "error": {
    "code": "RATE_LIMITED",
    "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

503 Service Unavailable

A downstream service is temporarily unavailable. Retry the request after a short delay.

{
  "error": {
    "code": "PURCHASE_CHECK_FAILED",
    "message": "Purchase verification is temporarily unavailable. Please try again."
  }
}

Error Handling Best Practices

Always check the error.code 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://api.web3.market/api/templates/42/download', {
  headers: {
    'X-API-Key': apiKey,
    'Accept': 'application/json',
  },
});
 
if (response.ok) {
  const data = await response.json();
  // Success — use data.url to download
  return data;
}
 
const error = await response.json();
 
switch (error.error.code) {
  case 'UNAUTHORIZED':
    // API key is invalid — prompt user to check their key
    break;
  case 'NOT_FOUND':
    // Template does not exist
    break;
  case 'NOT_PURCHASED':
    // User needs to purchase the template first
    break;
  case 'RATE_LIMITED':
    // Wait and retry
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    break;
  case 'PURCHASE_CHECK_FAILED':
    // Downstream service issue — retry after a short delay
    break;
  case 'VALIDATION_ERROR':
    // Check the request body for missing or invalid fields
    break;
  default:
    // Unknown error — log and handle gracefully
    break;
}

Marketplace Rate Limits