Troubleshooting

Common Issues

The table below covers the most frequent problems users encounter when working with the Oathe API and audit reports.

Symptom	Cause	Solution
Audit stuck in queued	High server load or queue backlog	Check GET /health for queue_length. If the queue is large, wait and retry. Normal queue time is under 5 seconds.
404 Not Found on GET /api/audit/{id}	The audit ID does not exist or the skill has never been audited	Verify the audit_id is correct. If you are querying by slug, submit the skill first with POST /api/submit.
Status never reaches "completed"	The correct terminal status is "complete", not "completed"	Check for status === "complete" (no trailing “d”). This is a common string mismatch in client code.
400 Bad Request on POST	Wrong field name in the request body	The correct field is skill_url, not repo_url, url, or repository. Check your payload.
Response includes "deduplicated": true	The skill at this URL and commit was already audited	This is expected behavior. Use the returned audit_id to fetch the existing report. To force a new audit, include "force_rescan": true in the POST body.
Badge shows “not scanned”	No completed audit exists for this skill URL	Submit an audit and wait for it to reach complete status. The badge only displays scores from finished audits.
Audit returns failed status	The repository is unreachable or the skill could not be installed	Check the error field in the response. Common causes: private repo, invalid URL, missing entry point, dependency installation failure.
Trust score seems too low	Multiple findings are stacking in one dimension	Review the findings array and check score_impact values. Multiple findings in heavily weighted dimensions compound quickly.

Debugging API Requests

Verify the endpoint

All audit API calls go to https://audit-engine.oathe.ai. Make sure you are not hitting oathe.ai (the website) or an outdated endpoint.

Check the request format

A correct submission looks like this:

curl -X POST https://audit-engine.oathe.ai/api/submit \
  -H "Content-Type: application/json" \
  -d '{"skill_url": "https://github.com/your-org/your-skill"}'

The response includes an audit_id:

{
  "audit_id": "a-1b2c3d4e",
  "status": "queued",
  "stage_label": "Waiting in queue"
}

Inspect the health endpoint

curl https://audit-engine.oathe.ai/health

This returns system status, queue length, and worker availability. If the system reports degraded status, audits may take longer than usual.

Status Polling Checklist

If your integration is not picking up completed audits, walk through this checklist:

1. Correct status value: Compare against the string "complete", not "completed" or "done".
2. Polling interval: Use 3-5 second intervals. Polling faster than once per second may trigger rate limiting.
3. Timeout handling: Set a maximum wait time (e.g., 3 minutes). If the audit has not completed by then, check for "failed" status.
4. Error handling: Always check for "failed" as a terminal state in addition to "complete".

Webhook Troubleshooting

If your GitHub webhook is not triggering audits:

1. Check the webhook delivery log in GitHub > Settings > Webhooks > Recent Deliveries.
2. Verify the payload URL is exactly https://audit-engine.oathe.ai/api/webhook/github.
3. Confirm the content type is set to application/json (not application/x-www-form-urlencoded).
4. Ensure the webhook secret matches what Oathe expects. A mismatch results in 401 Unauthorized.
5. Check that the correct events are selected (push and/or release).

Still Stuck?

If none of the above resolves your issue, check the Audit Lifecycle page to understand the full status progression, or review the FAQ for additional context.