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 hitting the limit requires backoff in its retry logic or its own token limit. Limits and stores: Rate Limiting.

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 is set by RequestTrafficLogging:MaxFileSizeMB and MaxFileCount (Auditing).

Performance ​

Durations above 1000ms indicate a database, network or host problem. Slow request queries: SQLite storage.

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 levels: Health and Logs.

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