> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Errors Reference

> Quick reference for KnoxCall error codes and how to fix them. Troubleshoot 403, 404, 502, 504 errors and more.

# Common Errors Reference

Quick solutions to the most common KnoxCall errors.

***

## 403 Forbidden

### Error Message

```json theme={"dark"}
{
  "error": "Request could not be identified as an authorized client for the configured environment"
}
```

### What It Means

Your IP address isn't whitelisted for this route.

### Quick Fix

1. Check your IP: `curl https://api.ipify.org`
2. Go to **Resources** → **Clients**
3. Update or create client with your IP
4. Assign client to route

### See Also

[IP Authorization Issues Guide](/troubleshooting/ip-authorization-issues) - Comprehensive troubleshooting

***

## 404 Route Not Found

### Error Message

```json theme={"dark"}
{
  "error": "Route not found"
}
```

### What It Means

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

### Common Causes

#### 1. Typo in Route Name

```bash theme={"dark"}
# ❌ 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:**

1. Go to **Routes**
2. Find your route
3. 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

```bash theme={"dark"}
# 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

```json theme={"dark"}
{
  "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

```bash theme={"dark"}
# ❌ 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:

```bash theme={"dark"}
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 77-character key?
* Is it the correct key for this tenant?
* Has the key been deleted?

**Solution:**

1. Go to **Settings** → **Tenant** tab → **API Keys**
2. Verify key exists and is enabled
3. 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

```json theme={"dark"}
{
  "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:**

```bash theme={"dark"}
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:**

1. Go to **Routes** → Your route
2. Look at **Target Base URL**
3. Is it correct?

**Common mistakes:**

```text theme={"dark"}
❌ 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:**

```json theme={"dark"}
{
  "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:**

```bash theme={"dark"}
curl https://your-backend.com
```

**If "Could not resolve host":** DNS issue. Check domain registration and DNS records.

***

## 504 Gateway Timeout

### Error Message

```json theme={"dark"}
{
  "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:**

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

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

### See Also

[504 Errors Deep Dive](/troubleshooting/troubleshooting-504-errors)

***

## 500 Internal Server Error

### Error Message

```json theme={"dark"}
{
  "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:**

```json theme={"dark"}
{
  "error": "Internal Server Error",
  "upstream_status": 500
}
```

→ Your backend returned 500 (backend problem)

**If error details show:**

```json theme={"dark"}
{
  "error": "Internal Server Error",
  "upstream_status": null
}
```

→ KnoxCall internal error (rare)

#### Backend 500 Errors

**Solution:**

1. Check your backend logs
2. Look for stack traces, exceptions
3. Fix the bug in your backend code
4. Common causes:
   * Null pointer exceptions
   * Missing environment variables
   * Database connection errors
   * Uncaught exceptions

#### KnoxCall 500 Errors

**Solution:**

1. Check **Logs** → **API Logs** for details
2. Contact support if it's a KnoxCall bug
3. Check if it's a secret resolution issue

***

## 429 Too Many Requests

### Error Message

```json theme={"dark"}
{
  "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:**

1. Go to **Routes** → Your route
2. Check **Rate Limiting** settings
3. 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-Related Errors

### Secret Not Found

**Error:**

```json theme={"dark"}
{
  "error": "Secret 'stripe_key' not found",
  "status": 500
}
```

**What It Means:** Route references a secret that doesn't exist.

**Solution:**

1. Go to **Resources** → **Secrets**
2. Check if `stripe_key` exists
3. If not, create it
4. If yes, check spelling in route config

### Template Syntax Error

**Error:**

```json theme={"dark"}
{
  "error": "Invalid template syntax in inject_headers_json"
}
```

**What It Means:** Wrong template format in route config.

**Common mistakes:**

```text theme={"dark"}
❌ {{stripe_key}}              (missing "secret:" prefix)
❌ {secret:stripe_key}          (single braces)
❌ {{ secret:stripe_key }}      (spaces inside braces)

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

### Secret Decryption Error

**Error:**

```json theme={"dark"}
{
  "error": "Failed to decrypt secret"
}
```

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

**Solution:**

1. Delete the secret
2. Recreate with same name
3. Update value
4. Test again

***

## Environment Errors

### Environment Not Found

**Error:**

```json theme={"dark"}
{
  "error": "Environment 'staging' not found",
  "status": 404
}
```

**What It Means:** You specified an environment that doesn't exist.

**Solution:**

1. Go to **Resources** → **Environments**
2. Check if "staging" exists
3. Create it if missing
4. Or use existing environment name

### No Override Configuration

**Error:**

```json theme={"dark"}
{
  "error": "No configuration found for environment 'staging'"
}
```

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

**Solution:**

1. Go to **Routes** → Your route
2. Click **Environment** tab
3. Add configuration for "staging" environment

***

## Network/Connection Errors

### ECONNREFUSED

**Error:**

```json theme={"dark"}
{
  "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:**

```json theme={"dark"}
{
  "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:**

```json theme={"dark"}
{
  "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](/troubleshooting/ip-authorization-issues) |
| `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:

```json theme={"dark"}
{
  "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

1. Go to **Logs** → **API Logs**
2. Find your failed request
3. Click to expand details
4. Look for:
   * Request headers sent
   * Response from backend
   * Error stack trace

### 3. Test Backend Directly

```bash theme={"dark"}
# 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

1. **Route enabled?** ✓
2. **Target URL correct?** ✓
3. **Methods allowed?** ✓
4. **Clients assigned?** ✓
5. **Secrets exist?** ✓

***

## Getting Help

If error persists:

<CardGroup cols={2}>
  <Card title="Debugging Routes" icon="bug" href="/troubleshooting/debugging-routes">
    Step-by-step debugging guide
  </Card>

  <Card title="API Logs" icon="list" href="/monitoring/api-logs">
    Review detailed request logs
  </Card>

  <Card title="IP Issues" icon="ban" href="/troubleshooting/ip-authorization-issues">
    Fix IP authorization problems
  </Card>

  <Card title="504 Errors" icon="clock" href="/troubleshooting/troubleshooting-504-errors">
    Timeout troubleshooting
  </Card>

  <Card title="Support Chat" icon="headset" href="/support/support-chat">
    Live help from support team
  </Card>
</CardGroup>

**When contacting support, include:**

1. Error message (full JSON response)
2. Request ID from logs
3. What you tried
4. 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

***

<Info>
  **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!
</Info>