Troubleshooting

Status codes ​

Authentication ​

A 401 means the token could not be verified. The header format:

Authorization: Bearer YOUR_TOKEN

Check under Access Tokens that the token exists and is neither expired nor archived. Failures from one integration indicate an outdated token in that deployment. Failures across many clients indicate a gateway change.

A 403 means the token is valid but its scopes, environments or tenants exclude the request. Compare the token's scopes and environments under Access Tokens with the endpoint's AllowedEnvironments and the scope patterns.

Rate limiting ​

Rate limit events in the log:

Select-String -Path ".\log\*.log" -Pattern "Rate limit" | Select-Object -Last 20

grep -h "Rate limit" ./log/*.log | tail -n 20

A single client or IP address hitting the limit needs backoff in its retry logic or its own token limit; general growth needs higher limits. A restart resets all counters of the Memory store:

sudo systemctl restart portway

docker compose restart portway

Restart-WebAppPool -Name "PortwayAppPool"

Database connections ​

SQL endpoints return 500 when the database is unreachable.

Connectivity test from the gateway host:

$conn = New-Object System.Data.SqlClient.SqlConnection
$conn.ConnectionString = "Server=YOUR_SERVER;Database=500;Trusted_Connection=True;"
try {
    $conn.Open()
    Write-Host "Connection successful"
} catch {
    Write-Host "Connection failed: $_"
} finally {
    $conn.Close()
}

sqlcmd -S YOUR_SERVER -d 500 -Q "SELECT 1" && echo "Connection successful"

Intermittent failures under load indicate an undersized pool (MaxPoolSize). Queries that stop at exactly CommandTimeout need a higher timeout or a faster query. Settings: SqlConnectionPooling.

Proxy endpoints ​

Unreachable upstreams return timeouts, "Error processing endpoint" or 503. Direct test from the gateway host:

Invoke-WebRequest -Uri "http://localhost:8020/services/Exact.Entity.REST.EG/Account" -UseDefaultCredentials

curl -I http://localhost:8020/services/Exact.Entity.REST.EG/Account

When the direct request succeeds, compare the endpoint's Url and the environment's settings.json headers with what the upstream expects. Blocked hosts: Network access policy.

Health checks ​

The detailed health check (GET /health/details, with a token) names the failing check. The startup log lists unhealthy proxy endpoints in one Health check status: Unhealthy proxy endpoints detected warning; the reason per endpoint is logged at Debug.

Disk space ​

Low disk space reports Unhealthy and eventually stops log writes:

Get-PSDrive -PSProvider FileSystem
Get-ChildItem ".\log" -Recurse -File |
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
    Remove-Item -Force

df -h
find ./log -type f -mtime +30 -delete

Traffic log rotation:

{
  "RequestTrafficLogging": {
    "MaxFileSizeMB": 50,
    "MaxFileCount": 5
  }
}

Performance ​

Durations above 1000ms indicate a database, network or host problem. With SQLite traffic logging:

SELECT Path, QueryString, DurationMs, StatusCode
FROM TrafficLogs
WHERE DurationMs > 1000
ORDER BY DurationMs DESC
LIMIT 20;

Logs ​

Recent errors and a live tail:

Select-String -Path ".\log\*.log" -Pattern "\[ERR\]|\[FTL\]" | Select-Object -Last 50
Get-Content ".\log\portwayapi-$(Get-Date -Format 'yyyyMMdd').log" -Wait -Tail 50

grep -hE "\[ERR\]|\[FTL\]" ./log/*.log | tail -n 50
tail -n 50 -f "./log/portwayapi-$(date +%Y%m%d).log"

Log message patterns:

[WRN] Rate limit enforced for {Identifier}, retry after {Seconds}s (at {Time})
[WRN] Tokens detected in the tokens directory; relocate them to a secure location
[DBG] SQL Query Request: {Url}

Application not starting ​

Host state and startup output:

systemctl status portway
journalctl -u portway -n 100

docker compose ps
docker compose logs --tail=100 portway

Get-EventLog -LogName Application -Source "IIS*" -Newest 20
Get-WebAppPoolState -Name "PortwayAppPool"

Startup errors in the application log:

grep -hE "\[ERR\]|\[FTL\]" ./log/portwayapi-*.log | head -50

Select-String -Path ".\log\portwayapi-*.log" -Pattern "\[ERR\]|\[FTL\]" | Select-Object -First 50

Related topics ​

• Health and Logs
• Security
• Deployment
• SQL Endpoints