ProductDocsPricingBlog

Troubleshooting

Common errors and fixes when integrating NjiraAI.

Authentication errors

401 Unauthorized

Cause: Invalid or missing API key.

Fix:

  • Ensure your API key is included in the Authorization header: Authorization: Bearer nj_live_YOUR_KEY
  • Verify the key is active in the Console under Settings → API Keys
  • Key format: nj_live_* (production) or nj_test_* (test)
# Verify your key works:
curl -s -o /dev/null -w "%{http_code}" \
  https://gateway.njira.ai/health \
  -H "Authorization: Bearer nj_live_YOUR_KEY"
# Expected: 200

403 Forbidden (unexpected)

Cause: A policy is blocking your request.

# Check the response body for the reason:
curl -s https://gateway.njira.ai/v1/chat/completions \
  -H "Authorization: Bearer nj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.2","messages":[{"role":"user","content":"your message"}]}' | jq .

Look at the reason_code and reason fields. If it's a false positive:

  1. Switch to shadow mode in the Console to unblock traffic while you investigate
  2. Adjust the policy pack rules in the Console under Policies
  3. Re-enable enforcement once the policy is tuned

Connection errors

Connection refused or timeout

Cause: Incorrect Gateway URL or network issue.

Fix:

  • Verify you are using the correct Gateway URL: https://gateway.njira.ai
  • For SDK users, check the base_url / baseUrl configuration points to https://api.njira.ai
  • Check the NjiraAI status page for any ongoing incidents

Verdict issues

All requests returning ALLOW (no enforcement)

Cause: Shadow mode may be enabled, or no policies are active.

Fix:

  1. Check enforcement mode in the Console under Settings → Enforcement
  2. Verify at least one policy is active under Policies
  3. If in shadow mode, response headers will include X-Njira-Shadow-Verdict showing what would have been enforced

Unexpected BLOCK verdicts

Cause: A policy rule is matching content you consider safe.

Fix:

  1. Check the reason_code in the 403 response body
  2. Use the Simulate feature in the Console (Policies → Simulate) to test the input against your active policies
  3. Adjust the matching rule or add an exception

SDK errors

govern() returns an error

Possible causes:

  • Invalid API key → check api_key parameter
  • Wrong base URL → use https://api.njira.ai
  • Network connectivity issue
# Python — verify SDK connectivity
import njiraai
client = njiraai.Client(api_key="nj_live_YOUR_KEY", base_url="https://api.njira.ai")
verdict = client.govern(input="test", tool_name="test")
print(verdict.action)  # Should print "ALLOW"

// TypeScript — verify SDK connectivity
import { NjiraAI } from '@njiraai/sdk';
const njira = new NjiraAI({ apiKey: 'nj_live_YOUR_KEY', baseUrl: 'https://api.njira.ai' });
const verdict = await njira.govern({ input: 'test', toolName: 'test' });
console.log(verdict.action);  // Should print "ALLOW"

Performance

High latency on verdicts

Check the X-Njira-Latency-Ms response header:

curl -s -D - https://gateway.njira.ai/v1/chat/completions \
  -H "Authorization: Bearer nj_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.2","messages":[{"role":"user","content":"test"}]}' \
  2>&1 | grep -i njira

Targets:

  • Pattern/regex rules: < 20ms
  • Hazmat scanner: < 100ms
  • Full pipeline: < 200ms

If latency is consistently high, try using the fast tier via the X-Njira-Tier: fast header for latency-sensitive requests.

Getting help