Error Reference

Complete reference for PageGun API error codes, meanings, and solutions. All API errors follow a consistent structure and include actionable information to help you resolve issues quickly.

Error Response Structure

All API errors return a JSON object with the following structure:

{
  "statusCode": 400,
  "name": "error_code_here",
  "message": "Human-readable error description"
}

Response Fields

Field	Type	Description
`statusCode`	number	HTTP status code
`name`	string	Machine-readable error identifier
`message`	string	Human-readable error description

HTTP Status Codes

Status	Meaning	When It Occurs
`400`	Bad Request	Invalid request format, missing required fields, or validation errors
`401`	Unauthorized	Missing, invalid, or expired API key
`403`	Forbidden	Valid authentication but insufficient permissions
`404`	Not Found	Requested resource doesn't exist or you don't have access
`409`	Conflict	Resource already exists or conflicts with current state
`422`	Unprocessable Entity	Request is well-formed but contains logical errors
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side error (contact support if persistent)
`503`	Service Unavailable	Temporary service interruption or maintenance

Common Error Codes

Authentication Errors

`unauthorized`

HTTP Status: 401

{
  "statusCode": 401,
  "name": "unauthorized",
  "message": "Invalid or missing API key"
}

Causes:

No Authorization header provided
Invalid API key format
Expired or revoked API key
API key for wrong environment (test vs live)

Solutions:

Include Authorization: Bearer $PAGEGUN_API_KEY header
Verify API key is correct and active
Check you're using the right environment key
Generate a new API key if needed

`forbidden`

HTTP Status: 403

{
  "statusCode": 403,
  "name": "forbidden",
  "message": "You don't have permission to access this resource"
}

Causes:

Trying to access another user's project/page
API key lacks required permissions
Resource is restricted to higher plan tiers

Solutions:

Verify you're accessing your own resources
Check API key permissions in dashboard
Upgrade plan if accessing premium features

Validation Errors

`invalid_request`

HTTP Status: 400

{
  "statusCode": 422,
  "name": "invalid_request",
  "message": "Request validation failed"
}

Causes:

Missing required fields
Invalid field formats or values
Data type mismatches
Constraint violations

Solutions:

Check all required fields are provided
Validate field formats match API specifications
Ensure data types are correct (string vs number vs boolean)
Review field constraints (length, allowed characters, etc.)

`validation_error`

HTTP Status: 422

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Invalid section configuration"
}

Causes:

Invalid section types in page config
Missing required section properties
Invalid URLs or references
Circular references in content

Solutions:

Use only supported section types
Include all required properties for each section
Validate URLs and references
Check for circular dependencies

Resource Errors

`not_found`

HTTP Status: 404

{
  "statusCode": 404,
  "name": "not_found",
  "message": "Page not found"
}

Causes:

Resource ID doesn't exist
Resource was deleted
No access permissions to resource
Using wrong environment (test vs live)

Solutions:

Verify resource ID is correct
Check resource still exists
Ensure you have access permissions
Confirm you're using the right environment

`conflict`

HTTP Status: 409

{
  "statusCode": 409,
  "name": "conflict",
  "message": "Slug already exists"
}

Causes:

Duplicate slugs in same subroute
Domain already in use
Resource name conflicts
Concurrent modifications

Solutions:

Choose a unique slug for the subroute
Use a different domain
Add suffixes or prefixes to make names unique
Retry after a brief delay for concurrent updates

Rate Limiting

`rate_limit_exceeded`

HTTP Status: 429

{
  "statusCode": 429,
  "name": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later."
}

Causes:

Exceeded requests per minute limit
Burst limit exceeded
IP-based rate limiting triggered

Solutions:

Implement exponential backoff
Respect Retry-After header
Reduce request frequency
Cache responses when possible
Consider upgrading to higher rate limits

Server Errors

`internal_error`

HTTP Status: 500

{
  "statusCode": 500,
  "name": "internal_error",
  "message": "An internal server error occurred. Please try again."
}

Causes:

Temporary server issues
Database connectivity problems
Service dependencies unavailable

Solutions:

Retry the request after a delay
Implement exponential backoff
Contact support with request ID if persistent
Check status page for known issues

`service_unavailable`

HTTP Status: 503

{
  "statusCode": 503,
  "name": "service_unavailable",
  "message": "Service temporarily unavailable for maintenance"
}

Causes:

Scheduled maintenance
Service overload
Emergency maintenance

Solutions:

Wait and retry after maintenance window
Check status page for updates
Implement graceful degradation in your app

Error Handling Best Practices

1. Implement Proper Error Handling

const apiRequest = async (url, options) => {
  try {
    const response = await fetch(url, options);
    
    if (!response.ok) {
      const error = await response.json();
      throw new APIError(error, response.status);
    }
    
    return response.json();
  } catch (error) {
    if (error instanceof APIError) {
      // Handle API errors
      console.error(`API Error: ${error.name} - ${error.message}`);
      return handleAPIError(error);
    } else {
      // Handle network errors
      console.error('Network error:', error.message);
      throw error;
    }
  }
};

class APIError extends Error {
  constructor(errorData, status) {
    super(errorData.message);
    this.name = errorData.name;
    this.statusCode = errorData.statusCode;
    this.status = status;
  }
}

2. Implement Retry Logic

const retryRequest = async (requestFn, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        // Rate limited - wait and retry
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      } else if (error.status >= 500 && attempt < maxRetries) {
        // Server error - retry
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      } else {
        // Don't retry client errors or final attempt
        throw error;
      }
    }
  }
};

3. Validate Before Sending

const validatePageData = (pageData) => {
  const errors = {};
  
  if (!pageData.page_name || pageData.page_name.trim() === '') {
    errors.page_name = 'Page name is required';
  }
  
  if (pageData.slug && !/^[a-z0-9-]{3,100}$/.test(pageData.slug)) {
    errors.slug = 'Slug must be 3-100 characters, lowercase letters, numbers, and hyphens only';
  }
  
  if (Object.keys(errors).length > 0) {
    throw new ValidationError(errors);
  }
};

4. User-Friendly Error Messages

const getErrorMessage = (error) => {
  const userFriendlyMessages = {
    'unauthorized': 'Please check your API key and try again.',
    'forbidden': 'You don\'t have permission to perform this action.',
    'not_found': 'The requested item could not be found.',
    'conflict': 'This item already exists. Please choose a different name.',
    'rate_limit_exceeded': 'Too many requests. Please wait a moment and try again.',
    'internal_error': 'Something went wrong on our end. Please try again.',
    'validation_error': 'Please check your input and try again.'
  };
  
  return userFriendlyMessages[error.name] || 'An unexpected error occurred.';
};

Getting Help

If you encounter persistent errors:

Check the Status Page: Visit status.pagegun.com for known issues
Review Documentation: Ensure you're following the API specifications correctly
Contact Support: Include the full error response and request ID when contacting support
Community: Ask questions in the PageGun community forum

Status Page

Monitor API availability and incidents at status.pagegun.com.

Rate Limits

Current rate limits by plan:

Plan	Requests per Minute	Requests per Hour	Burst Limit
Free	60	1,000	10
Pro	300	10,000	50
Business	1,000	50,000	100
Enterprise	Custom	Custom	Custom

Rate limits are per API key and reset at the beginning of each window.