Error Codes

Error Response Format

All error responses return a JSON object with three fields:

{
  "statusCode": 400,
  "name": "validation_error",
  "message": "Invalid repository URL format."
}

Status Codes

Code	Meaning	When It Occurs
200	OK	Successful GET request.
201	Created	Audit successfully submitted via POST.
400	Bad Request	Invalid input — malformed URL, missing fields, or unsupported format.
404	Not Found	Audit ID does not exist, or no audit found for the given skill.
405	Method Not Allowed	Wrong HTTP method for the endpoint.
409	Conflict	Resource state conflict (e.g., audit already complete).
422	Unprocessable Entity	Idempotency key body mismatch. See Idempotency.
429	Rate Limited	Submission rate limit exceeded. See Rate Limits.
500	Server Error	Internal failure. Retry after a short delay. If persistent, report the issue.

URL Validation Rules

The skill_url field submitted to POST /api/submit must satisfy the following rules:

Accepted Formats

https://github.com/{owner}/{repo}
https://github.com/{owner}/{repo}/tree/{branch}/{path}

• The URL must use the https scheme.
• The host must be github.com.
• {owner} and {repo} must contain only alphanumeric characters, hyphens, underscores, and periods.
• /tree/ paths are used for monorepo subdirectory audits. The branch and path segments are required when /tree/ is present.

Restricted Characters

The following are rejected in the owner, repo, branch, or path segments:

• Spaces and whitespace characters.
• Query strings (?) and fragments (#).
• Encoded traversal sequences (.., %2e%2e).
• Null bytes and control characters.

Invalid Examples

URL	Reason
http://github.com/owner/repo	HTTP not accepted; must be HTTPS.
https://gitlab.com/owner/repo	Only GitHub URLs are supported.
https://github.com/owner/repo/tree/	Missing branch and path after /tree/.
https://github.com/owner/../repo	Path traversal not allowed.
https://github.com/owner/repo?ref=main	Query strings not accepted.

Common Errors

name	Status	Message
validation_error	400	Invalid repository URL format.
validation_error	400	Missing required field: skill_url.
audit_not_found	404	Audit not found.
skill_not_found	404	No audit found for this skill.
method_not_allowed	405	HTTP method not allowed.
conflict	409	Audit already complete.
idempotency_mismatch	422	Request body does not match the original request for this idempotency key.
rate_limited	429	Rate limited. Please wait before retrying.
internal_error	500	Internal server error.

Debugging Tips

• Double-check URL formatting before submitting. Copy the URL directly from the GitHub repository page to avoid typos.
• If you receive a 404 on a summary endpoint, the skill may not have been audited yet. Submit it via POST /api/submit first.
• For 500 errors, include the audit_id (if available) when reporting the issue so the team can trace the failure.