Error Code Reference

Every PatchOps Guard API error returns a structured JSON body with a machine-readable code (PG-XYYY), a human-readable message, and a suggested fix. 47 error codes across 6 categories.

{
  "error": {
    "code": "PG-1003",
    "message": "API key expired",
    "detail": "Your API key pk_live_...abc expired on 2026-04-15.",
    "fix": "Generate a new key at Settings → API Keys.",
    "docs": "https://patchguard.ai/guide#api-keys"
  }
}

🔍

Authentication

PG-1xxx

Errors related to API keys, sessions, and authorization.

Code	Message	Status	How to Fix
PG-1001	Missing authentication	401	Include 'Authorization: Bearer pk_live_...' header or login via /auth/github/start
PG-1002	Invalid API key	401	Check your key at Settings → API Keys. Keys start with pk_live_ or pk_test_.
PG-1003	API key expired	401	Generate a new key at Settings → API Keys.
PG-1004	Insufficient API key scope	403	This endpoint requires a specific scope. Update your key's scopes at Settings → API Keys.
PG-1005	Session expired	401	Log in again via /login.
PG-1006	2FA verification required	403	Provide your TOTP code or use a backup code.
PG-1007	Organization access denied	403	Your API key does not belong to this organization. Switch org at Settings → Organizations.
PG-1008	IP address not allowed	403	Your organization restricts API access by IP. Update allowed CIDRs at Settings → Security.

Input Validation

PG-2xxx

Errors caused by malformed or invalid request parameters.

Code	Message	Status	How to Fix
PG-2001	Invalid JSON body	400	Ensure the request body is valid JSON.
PG-2002	Missing required field	400	Check the API docs for required fields.
PG-2003	Invalid severity value	400	Use one of: critical, high, medium, low.
PG-2004	Invalid finding kind	400	Use one of: cve, container, iac, secret, sast, malpkg, llm, model, mcp, agent.
PG-2005	Invalid repository URL	400	Provide a valid GitHub/GitLab/Bitbucket repository URL.
PG-2006	Unknown package ecosystem	400	Supported: pypi, npm, go, maven, cargo, nuget, composer, pub, swiftpm, hex, hackage, cran, rubygems.
PG-2007	Invalid UUID format	400	IDs must be valid UUID v4 strings.
PG-2008	Invalid pagination parameters	400	'page' must be >= 1, 'per_page' must be 1–100.
PG-2009	Invalid SBOM format	400	Use one of: cyclonedx, spdx.
PG-2010	Invalid filter expression	400	Check the filter syntax in the API docs.

Resource

PG-3xxx

The requested resource was not found or conflicts with existing state.

Code	Message	Status	How to Fix
PG-3001	Resource not found	404	Verify the resource ID. It may have been deleted.
PG-3002	Repository not found	404	Check the repository ID or connect it at /onboarding.
PG-3003	Finding not found	404	Verify the finding ID. Findings from disconnected repos are archived.
PG-3004	Organization not found	404	Complete onboarding at /onboarding.
PG-3005	Repair job not found	404	Check the job ID. Repair jobs are retained for 90 days.
PG-3006	API key not found	404	The key may have been revoked. List active keys at Settings → API Keys.
PG-3007	Webhook endpoint not found	404	Check your webhook configuration at Settings → Integrations.
PG-3008	Organization member not found	404	The member may have left the organization.
PG-3009	Resource already exists	409	A resource with this identifier already exists. Use a different value or update the existing one.
PG-3010	Repair already in progress	409	Wait for the current repair to complete, or cancel it first.

Rate Limits & Quotas

PG-4xxx

You have exceeded a rate limit, plan quota, or concurrency ceiling.

Code	Message	Status	How to Fix
PG-4001	Rate limit exceeded	429	Wait and retry. Default: 1,000 requests/hour per API key.
PG-4002	AI repair monthly quota exceeded	429	Upgrade your plan for more AI repairs at /pricing.
PG-4003	Scan quota exceeded	429	Upgrade your plan for more scans at /pricing.
PG-4004	Repository limit reached	429	Upgrade your plan to connect more repos at /pricing.
PG-4005	Request payload too large	413	Maximum request body size is 10 MB.
PG-4006	Concurrent repair limit reached	429	Maximum 5 simultaneous repair jobs per organization. Wait for one to finish.

Server

PG-5xxx

Internal platform errors. These are usually transient.

Code	Message	Status	How to Fix
PG-5001	Internal server error	500	If this persists, contact help@bitmax.im.
PG-5002	Database error	503	Try again in a few seconds.
PG-5003	Queue service unavailable	503	Background tasks may be delayed. Try again shortly.
PG-5004	Sandbox execution failed	500	Retry the repair. If this persists, contact help@bitmax.im.
PG-5005	Database migration required	503	Run 'alembic upgrade head' and restart the server.
PG-5006	Scheduled maintenance	503	Check https://status.patchguard.ai for updates.

External Services

PG-6xxx

Upstream API failures from third-party services.

Code	Message	Status	How to Fix
PG-6001	GitHub API error	502	Check GitHub status at githubstatus.com.
PG-6002	AI service unavailable	503	The AI repair engine is temporarily unavailable. Try again shortly.
PG-6003	CVE data source unavailable	503	NVD/OSV may be experiencing issues. Findings are cached locally.
PG-6004	GitLab API error	502	Check GitLab status at status.gitlab.com.
PG-6005	Bitbucket API error	502	Check Bitbucket status at bitbucket.status.atlassian.com.
PG-6006	Static analysis engine error	503	Retry the repair. The re-scan step will be retried automatically.
PG-6007	Payment service error	502	Billing operations are temporarily unavailable. Try again shortly.

Still stuck?

Contact our support team or check the full API reference.

API Reference Contact Support