Common Errors Reference

Quick solutions to the most common KnoxCall errors.

403 Forbidden

Error Message

{
  "error": "IP address not authorized for this route",
  "status": 403,
  "ip": "203.45.67.89"
}

What It Means

Your IP address isn’t whitelisted for this route.

Quick Fix

Check your IP: curl https://api.ipify.org
Go to Resources → Clients
Update or create client with your IP
Assign client to route

404 Route Not Found

Error Message

{
  "error": "Route not found",
  "status": 404,
  "route": "user-api"
}

What It Means

The route name in your x-knoxcall-route header doesn’t exist.

Common Causes

1. Typo in Route Name

# ❌ Wrong
-H "x-knoxcall-route: user-ap1"  # Typo: "ap1" instead of "api"

# ✅ Correct
-H "x-knoxcall-route: user-api"

Solution: Double-check spelling. Route names are case-sensitive.

2. Route Disabled

Check:

Go to Routes
Find your route
Is Enabled toggle ON?

Solution: Enable the route.

3. Route Deleted

Symptom: Route worked before, now 404. Solution: Someone deleted it. Recreate the route or check with your team.

4. Wrong Environment

# Route exists in "production" but you're calling "staging"
-H "x-knoxcall-environment: staging"

Solution:

Use correct environment name
Or create route in the environment you’re calling

401 Unauthorized

Error Message

{
  "error": "Invalid API key",
  "status": 401
}

What It Means

Your KnoxCall API key (x-knoxcall-key) is invalid or missing.

Common Causes

1. Missing API Key

# ❌ Missing x-knoxcall-key header
curl https://a1b2c3d4.acme.knoxcall.com/api/users \
  -H "x-knoxcall-route: user-api"

Solution: Add the API key header:

curl https://a1b2c3d4.acme.knoxcall.com/api/users \
  -H "x-knoxcall-key: tk_abc123..." \
  -H "x-knoxcall-route: user-api"

2. Wrong API Key

Check:

Did you copy the full 72-character key?
Is it the correct key for this tenant?
Has the key been deleted?

Solution:

Go to Settings → API Keys
Verify key exists and is enabled
Generate new key if needed

3. API Key Deleted

Symptom: Worked before, now 401. Solution: Someone deleted the key. Generate a new one.

502 Bad Gateway

Error Message

{
  "error": "Bad Gateway",
  "status": 502,
  "message": "Error connecting to upstream server"
}

What It Means

KnoxCall couldn’t connect to your backend API.

Common Causes

1. Backend Server Down

Your backend API isn’t running or crashed. Test directly:

curl https://your-backend-api.com/api/users

If this fails: Your backend is down. Restart it.

2. Wrong Target URL

Route points to incorrect backend URL. Check:

Go to Routes → Your route
Look at Target Base URL
Is it correct?

Common mistakes:

❌ https://api.example.com/api  (extra /api)
✅ https://api.example.com

❌ http://localhost:3000  (localhost not accessible)
✅ https://your-server.com

3. Firewall Blocking

Your backend firewall is blocking KnoxCall’s requests. Solution:

Whitelist KnoxCall’s IP addresses in your backend firewall
Or disable firewall for testing (not recommended for production)

4. SSL/TLS Issues

Backend has invalid SSL certificate. Symptoms:

{
  "error": "SSL certificate problem: self signed certificate"
}

Solution:

Use valid SSL certificate on backend
Don’t use self-signed certs in production

5. DNS Not Resolving

Backend domain doesn’t exist or isn’t resolving. Test:

curl https://your-backend.com

If “Could not resolve host”: DNS issue. Check domain registration and DNS records.

504 Gateway Timeout

Error Message

{
  "error": "Gateway Timeout",
  "status": 504,
  "message": "Upstream server did not respond in time"
}

What It Means

Your backend API took too long to respond (>30 seconds default).

Common Causes

1. Slow Backend Processing

Your API is taking forever to process the request. Examples:

Heavy database query
Third-party API call timing out
Large file processing
Infinite loop in code

Solution:

Optimize your backend code
Add database indexes
Use async processing for long tasks
Implement timeouts on third-party calls

2. Backend Deadlock

Your backend is stuck waiting for something. Check:

Database connections maxed out?
Waiting for external service?
Thread pool exhausted?

Solution: Restart backend server, investigate logs.

3. Network Latency

Slow network between KnoxCall and your backend. Test:

curl -w "Time: %{time_total}s\n" https://your-backend.com/api/test

If >30 seconds: Network or backend is too slow.

500 Internal Server Error

Error Message

{
  "error": "Internal Server Error",
  "status": 500
}

What It Means

Either KnoxCall or your backend had an unexpected error.

How to Debug

Check Which Side Failed

If error details show:

{
  "error": "Internal Server Error",
  "upstream_status": 500
}

→ Your backend returned 500 (backend problem) If error details show:

{
  "error": "Internal Server Error",
  "upstream_status": null
}

→ KnoxCall internal error (rare)

Backend 500 Errors

Solution:

Check your backend logs
Look for stack traces, exceptions
Fix the bug in your backend code
Common causes:
- Null pointer exceptions
- Missing environment variables
- Database connection errors
- Uncaught exceptions

KnoxCall 500 Errors

Solution:

Check Logs → API Logs for details
Contact support if it’s a KnoxCall bug
Check if it’s a secret resolution issue

429 Too Many Requests

Error Message

{
  "error": "Too Many Requests",
  "status": 429,
  "retry_after": 60
}

What It Means

You’ve hit a rate limit.

Common Causes

1. Route Rate Limit

Your route has rate limiting enabled. Check:

Go to Routes → Your route
Check Rate Limiting settings
What’s the limit? (e.g., 100 requests/minute)

Solution:

Slow down your requests
Increase rate limit (if you control it)
Use exponential backoff and retry

2. API Key Rate Limit

Your API key has a global rate limit. Solution: Wait for the rate limit window to reset (check retry_after in response).

3. Burst Traffic

You sent a burst of requests all at once. Solution:

Implement request queuing
Add delays between requests
Use connection pooling

Secret Not Found

Error:

{
  "error": "Secret 'stripe_key' not found",
  "status": 500
}

What It Means: Route references a secret that doesn’t exist. Solution:

Go to Resources → Secrets
Check if stripe_key exists
If not, create it
If yes, check spelling in route config

Template Syntax Error

Error:

{
  "error": "Invalid template syntax in inject_headers_json"
}

What It Means: Wrong template format in route config. Common mistakes:

❌ {{stripe_key}}              (missing "secret:" prefix)
❌ {secret:stripe_key}          (single braces)
❌ {{ secret:stripe_key }}      (spaces inside braces)

✅ {{secret:stripe_key}}        (correct!)

Secret Decryption Error

Error:

{
  "error": "Failed to decrypt secret"
}

What It Means: Secret value is corrupted or encryption key changed. Solution:

Delete the secret
Recreate with same name
Update value
Test again

Environment Errors

Environment Not Found

Error:

{
  "error": "Environment 'staging' not found",
  "status": 404
}

What It Means: You specified an environment that doesn’t exist. Solution:

Go to Resources → Environments
Check if “staging” exists
Create it if missing
Or use existing environment name

No Override Configuration

Error:

{
  "error": "No configuration found for environment 'staging'"
}

What It Means: Environment exists but has no config for this route. Solution:

Go to Routes → Your route
Click Environment Overrides
Add configuration for “staging” environment

Network/Connection Errors

ECONNREFUSED

Error:

{
  "error": "connect ECONNREFUSED 127.0.0.1:3000"
}

What It Means: Backend server is not running or not listening on that port. Solution:

Start your backend server
Check port is correct
Don’t use localhost/127.0.0.1 (not accessible from KnoxCall)

ENOTFOUND

Error:

{
  "error": "getaddrinfo ENOTFOUND api.example.com"
}

What It Means: DNS lookup failed. Domain doesn’t exist. Solution:

Check domain spelling
Verify domain is registered
Check DNS records are configured

ETIMEDOUT

Error:

{
  "error": "connect ETIMEDOUT"
}

What It Means: Connection attempt timed out (before request even sent). Solution:

Check backend is accessible from internet
Verify firewall allows incoming connections
Check backend server isn’t crashed

Client/Authorization Errors (Summary)

Error	Meaning	Fix
`IP address not authorized`	IP not whitelisted	See IP Authorization Guide
`Client authorization required`	Route needs client but none provided	Assign client to route
`No clients assigned to environment`	Environment has no clients	Assign clients to environment
`Client disabled`	Client exists but disabled	Enable client

Error Response Format

All KnoxCall errors follow this format:

{
  "error": "Error message here",
  "status": 403,
  "details": {
    // Additional context
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "request_id": "req_abc123xyz"
}

Use request_id when contacting support!

Quick Debugging Steps

Follow these steps for any error:

1. Check Error Code

Code	Category	Priority
401	Authentication	Check API key
403	Authorization	Check IP/client
404	Not Found	Check route name
429	Rate Limit	Slow down requests
500	Server Error	Check backend logs
502	Bad Gateway	Check backend URL/status
504	Timeout	Check backend performance

2. Check Logs

Go to Logs → API Logs
Find your failed request
Click to expand details
Look for:
- Request headers sent
- Response from backend
- Error stack trace

3. Test Backend Directly

# Bypass KnoxCall, call backend directly
curl https://your-backend-api.com/api/test

If this fails: Problem is with your backend, not KnoxCall.

4. Check Route Configuration

Route enabled? ✓
Target URL correct? ✓
Methods allowed? ✓
Clients assigned? ✓
Secrets exist? ✓

Getting Help

If error persists:

Debugging Routes

Step-by-step debugging guide

API Logs

Review detailed request logs

IP Issues

Fix IP authorization problems

504 Errors

Timeout troubleshooting

Support Chat

Live help from support team

When contacting support, include:

Error message (full JSON response)
Request ID from logs
What you tried
Route name and configuration

Error Prevention Tips

For Development

✅ Use test API keys with “allow any IP”
✅ Test backend directly first
✅ Check logs after every change
✅ Start with simple route, add complexity gradually

For Production

✅ Use static IPs for servers
✅ Set up monitoring and alerts
✅ Test in staging environment first
✅ Have error handling in client code
✅ Implement retry logic with exponential backoff

General Best Practices

✅ Keep route names descriptive and unique
✅ Document what each secret is for
✅ Regularly audit and clean up unused clients
✅ Monitor API logs for patterns
✅ Set up health check endpoints

Pro Tip: 90% of errors are one of three things: IP authorization (403), route not found (404), or backend issues (502/504). Check these first!

Getting Started

Essentials: Routes

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Webhooks

Workflows

Security

Monitoring

Advanced Features

Infrastructure

Account

Troubleshooting

Support

About

​Common Errors Reference

​403 Forbidden

​Error Message

​What It Means

​Quick Fix

​See Also

​404 Route Not Found

​Error Message

​What It Means

​Common Causes

​1. Typo in Route Name

​2. Route Disabled

​3. Route Deleted

​4. Wrong Environment

​401 Unauthorized

​Error Message

​What It Means

​Common Causes

​1. Missing API Key

​2. Wrong API Key

​3. API Key Deleted

​502 Bad Gateway

​Error Message

​What It Means

​Common Causes

​1. Backend Server Down

​2. Wrong Target URL

​3. Firewall Blocking

​4. SSL/TLS Issues

​5. DNS Not Resolving

​504 Gateway Timeout

​Error Message

​What It Means

​Common Causes

​1. Slow Backend Processing

​2. Backend Deadlock

​3. Network Latency

​See Also

​500 Internal Server Error

​Error Message

​What It Means

​How to Debug

​Check Which Side Failed

​Backend 500 Errors

​KnoxCall 500 Errors

​429 Too Many Requests

​Error Message

​What It Means

​Common Causes

​1. Route Rate Limit

​2. API Key Rate Limit

​3. Burst Traffic

​Secret-Related Errors

​Secret Not Found

​Template Syntax Error

​Secret Decryption Error

​Environment Errors

​Environment Not Found

​No Override Configuration

​Network/Connection Errors

​ECONNREFUSED

​ENOTFOUND

​ETIMEDOUT

​Client/Authorization Errors (Summary)

​Error Response Format

Common Errors Reference

403 Forbidden

Error Message

What It Means

Quick Fix

See Also

404 Route Not Found

Error Message

What It Means

Common Causes

1. Typo in Route Name

2. Route Disabled

3. Route Deleted

4. Wrong Environment

401 Unauthorized

Error Message

What It Means

Common Causes

1. Missing API Key

2. Wrong API Key

3. API Key Deleted

502 Bad Gateway

Error Message

What It Means

Common Causes

1. Backend Server Down

2. Wrong Target URL

3. Firewall Blocking

4. SSL/TLS Issues

5. DNS Not Resolving

504 Gateway Timeout

Error Message

What It Means

Common Causes

1. Slow Backend Processing

2. Backend Deadlock

3. Network Latency

See Also

500 Internal Server Error

Error Message

What It Means

How to Debug

Check Which Side Failed

Backend 500 Errors

KnoxCall 500 Errors

429 Too Many Requests

Error Message

What It Means

Common Causes

1. Route Rate Limit

2. API Key Rate Limit

3. Burst Traffic

Secret-Related Errors

Secret Not Found

Template Syntax Error

Secret Decryption Error

Environment Errors

Environment Not Found

No Override Configuration

Network/Connection Errors

ECONNREFUSED

ENOTFOUND

ETIMEDOUT

Client/Authorization Errors (Summary)

Error Response Format

Quick Debugging Steps

1. Check Error Code

2. Check Logs

3. Test Backend Directly

4. Check Route Configuration

Getting Help

Error Prevention Tips

For Development

For Production

General Best Practices