Resources
Troubleshooting
Onboarding Issues

Onboarding Issues

This page covers the most common problems new users encounter during initial setup.

API key not working

Symptom

Requests return 401 Unauthorized:

{
  "error": "INVALID_API_KEY",
  "message": "The API key provided is invalid or has been revoked.",
  "status": 401
}

Causes and fixes

Wrong header name — NAT uses X-API-Key, not Authorization: Bearer.

# ✅ Correct
curl https://api.nat-testing.io/api/v1/usage \
  -H "X-API-Key: $NAT_API_KEY"
 
# ❌ Wrong
curl https://api.nat-testing.io/api/v1/usage \
  -H "Authorization: Bearer $NAT_API_KEY"

Key not yet provisioned — if you signed up very recently, wait a few seconds for the tenant provisioning to complete, then retry.

Key copied incorrectly — ensure the full key starting with nat_pk_ is included with no leading/trailing whitespace.

Key revoked — if you rotated your API key in the dashboard, the old key is immediately invalidated. Use the new key from Settings → API Keys (opens in a new tab).

To verify your key is valid, call GET /api/v1/usage — it requires authentication and returns a simple JSON response. A 200 OK confirms the key is working.

First scan failing

Symptom

POST /api/v1/scan returns an error immediately, or the scan reaches failed status shortly after starting.

Causes and fixes

Target URL unreachable — NAT's scanning agent must be able to reach your target URL. Make sure the host is publicly accessible (or, for self-hosted NAT, that it is reachable from where NAT is running).

# Test reachability from your environment
curl -I https://api.example.com

Invalid request body — the url field is required. If you supply a spec_url, it must be a valid URL pointing to a JSON or YAML OpenAPI specification.

{
  "url": "https://api.example.com",
  "spec_url": "https://api.example.com/openapi.json"
}

A 422 Unprocessable Entity response indicates a validation error:

{
  "error": "VALIDATION_ERROR",
  "message": "Field 'url' is required.",
  "status": 422
}

Target is localhost — localhost or 127.0.0.1 are not reachable by the SaaS scanner. Use a staging URL or set up self-hosted NAT if you need to scan local services.

Scan stuck in running — if a scan stays in running for more than 30 minutes without progress, it may have encountered a timeout. Use GET /api/v1/scan/{id} to check status. If it shows failed, start a new scan.

Quota exceeded on the Free plan

Symptom

New scan requests return 402 Payment Required:

{
  "error": "QUOTA_EXCEEDED",
  "message": "You have reached your monthly scan quota. Upgrade your plan or wait for quota reset.",
  "status": 402,
  "quota_reset_date": "2025-02-01T00:00:00Z"
}

Fixes

Wait for quota reset — quotas reset automatically on the first day of each billing period. Check quota_reset_date in the response or via GET /api/v1/usage.

Upgrade your plan — get more scans immediately by upgrading:

curl -X POST https://api.nat-testing.io/api/v1/billing/checkout \
  -H "X-API-Key: $NAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "success_url": "https://app.nat-testing.io/dashboard?upgraded=true",
    "cancel_url": "https://app.nat-testing.io/dashboard"
  }'

Or upgrade through the dashboard (opens in a new tab) under Settings → Billing → Upgrade Plan.

See Pricing & Plans for a full plan comparison.

The Free plan includes 50 functional scans per month. Security scans (POST /api/v1/security-scan) require the Pro plan or above.

Stripe checkout not completing

Symptom

You clicked Upgrade Plan or created a checkout session via the API, but the Stripe checkout page never loaded, returned an error, or you were redirected back without payment being processed.

Fixes

Pop-ups or redirect blockers — some browser extensions block third-party redirects. Try in an incognito window or a different browser.

Checkout session expired — Stripe checkout sessions expire after 24 hours. If you waited too long, create a new session:

curl -X POST https://api.nat-testing.io/api/v1/billing/checkout \
  -H "X-API-Key: $NAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "success_url": "https://app.nat-testing.io/dashboard",
    "cancel_url": "https://app.nat-testing.io/dashboard"
  }'

Card declined — Stripe provides a specific decline reason in the checkout flow. Common reasons include insufficient funds, card number typos, or fraud prevention triggers. Try a different payment method.

Plan already active — if your account already has an active Pro (or higher) subscription, you cannot start a new checkout for the same plan. Use POST /api/v1/billing/portal to manage your existing subscription instead:

curl -X POST https://api.nat-testing.io/api/v1/billing/portal \
  -H "X-API-Key: $NAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://app.nat-testing.io/dashboard"}'

Upgrade not reflected after payment — if the dashboard still shows the old plan after payment succeeds, wait up to 60 seconds for the Stripe webhook to process, then refresh the page. If it still shows the old plan after a few minutes, contact hello@nat-testing.io with your Stripe payment confirmation.

Sync-tenant errors

The POST /api/v1/billing/sync-tenant endpoint synchronizes tenant state between the NAT app and the engine. It is typically called automatically during provisioning, but you may encounter errors during manual setup.

409 Conflict — tenant already exists

{
  "error": "TENANT_ALREADY_EXISTS",
  "message": "A tenant with this ID is already registered.",
  "status": 409
}

This is safe to ignore. Your tenant is already provisioned. Use the existing API key from the response or from the dashboard.

422 Unprocessable Entity — missing fields

{
  "error": "VALIDATION_ERROR",
  "message": "Fields 'tenant_id' and 'email' are required.",
  "status": 422
}

Ensure your request body includes all required fields. Contact hello@nat-testing.io if you are unsure of the expected payload.

500 Internal Server Error

If sync-tenant consistently returns a 500, this may indicate an engine configuration issue. Check your engine logs if you are running self-hosted NAT. For SaaS, contact support.

Dashboard showing no data after first scan

Symptom

Your scan completed successfully (you received results from GET /api/v1/scan/{id}/results), but the dashboard at app.nat-testing.io (opens in a new tab) shows no scans or results.

Fixes

Browser cache — hard-refresh the dashboard (Ctrl+Shift+R or Cmd+Shift+R) to clear cached data.

Wrong account — ensure you are logged into the same account whose API key you used. Go to Settings → API Keys and verify the key prefix matches.

Dashboard delay — the dashboard may take up to 30 seconds to reflect newly completed scans. Wait and refresh.

Getting help

If you are still stuck after trying the steps above:

  • Documentation — search this docs site for the specific error message or endpoint
  • Email support — hello@nat-testing.io
  • Dashboard — include your scan ID and the full error response when contacting support

Related pages

Was this helpful?
FAQCommon API Errors