Troubleshooting

401 Unauthorized

Symptoms:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required..."
  }
}

Causes:

1. Missing API key (no header or query param)
2. Invalid API key format
3. API key not found in database
4. API key has been revoked
5. API key has expired

Solutions:

• Verify API key is set in environment variables
• Check key format: tento_pk_ or tento_sk_ prefix
• Confirm key exists in Admin UI (Settings → API Keys)
• Check key expiration date
• Rotate to new key if expired or revoked

404 Not Found

Symptoms:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Page with slug 'xyz' not found"
  }
}

Causes:

1. Page slug doesn't exist
2. Page exists but not published
3. Typo in slug
4. Page was deleted

Solutions:

• Verify slug in Admin UI (Pages)
• Check page status (must be "Published")
• Try other slugs to confirm API is working
• Check slug history if page was renamed

429 Rate Limited

Symptoms:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests..."
  }
}

Causes:

1. Exceeded 600 read requests per minute (per API key)
2. Exceeded the coarser per-IP WAF backstop
3. Multiple clients sharing same IP (WAF counts per IP)

Solutions:

• Implement exponential backoff retry
• Add request queuing
• Use pagination instead of many individual requests
• Implement client-side caching
• Use field selection to reduce API calls
• Wait for Retry-After seconds

Empty Response Data

Symptoms:

{
  "data": [],
  "pagination": { "total": 0 }
}

Causes:

1. No published pages exist
2. Filters too restrictive (type, search)
3. Wrong tenant (API key from different tenant)

Solutions:

• Remove filters to see all pages
• Verify pages are published in Admin UI
• Check API key is for correct tenant
• Confirm pages exist for the page type filter

Slow Responses

Symptoms:

• Requests taking > 1 second
• Timeouts

Causes:

1. Large payload (no field selection)
2. Fetching many pages without pagination
3. Cold cache (first request)
4. Network latency

Solutions:

• Use field selection: ?fields=title,excerpt
• Reduce pagination limit
• Implement caching (CDN, client-side)
• Use conditional requests with ETags
• Enable gzip compression in client

Incorrect Redirect Handling

Symptoms:

• Old slugs return 200 but URL doesn't change
• SEO penalties for duplicate content

Causes:

1. Not checking redirect field in response
2. Not implementing 301 redirect in framework

Solutions:

• Check for redirect field in response
• Implement framework redirect:

  if (data.redirect) {
    return {
      redirect: {
        destination: `/${data.redirect.to}`,
        permanent: true
      }
    }
  }
  

• Update canonical URL in meta tags