Error Reference

The RepoRisk API uses standard HTTP status codes. All error responses include a JSON body with a detail field describing the problem.

{
  "detail": "Human-readable error message"
}

401 Unauthorized

The request did not include a valid API key or the key cannot be found.

Valid keys start with the rrk_ prefix (e.g., rrk_live_AbCd…). They must be passed in the Authorization header as Authorization: Bearer <key>.

Cause	Resolution
`Authorization` header missing	Add `Authorization: Bearer <key>` to the request
Key does not exist or was never valid	Verify you copied the key correctly at creation time
Key hash mismatch	Regenerate a new key — the original cannot be recovered
Key has been revoked	Generate a new key from the Settings page

The request was authenticated but the caller lacks permission for the requested operation.

`detail` message	Cause	Resolution
`"API keys cannot be managed via API key authentication"`	An API key was used on a key-management endpoint (`/api/v1/settings/api-keys`)	Use a Clerk browser session (log in via the web UI) for key management
`"This endpoint requires a Clerk session and cannot be accessed with an API key"`	An API key was used on an endpoint that requires interactive session auth	Use a Clerk browser session for this operation
`"API access is not available on your current plan"`	API key used on an endpoint, but the organization's plan tier does not allow API access (key management check)	Upgrade to Tier 3
`"API access requires a Tier 3 plan"`	API key authenticated, but the organization's plan tier does not allow API access (bearer token auth check)	Upgrade to Tier 3
`"Access denied: repository is outside the API key's sub-org scope"`	A sub-org-scoped key attempted to access a repository in a different sub-org	Use an org-wide key, or create a key scoped to the correct sub-org
`"Insufficient permissions"`	The authenticated user/key does not have admin role	Ensure the Clerk account used to create the key has org-admin role

The requested resource does not exist or is inaccessible to the authenticated key's organization.

Cause	Resolution
Repository ID does not exist	Confirm the `repo_id` from `GET /api/v1/repos`
Repository belongs to a different organization	Verify your key belongs to the correct organization
API key record not found during revocation	Key may already be revoked or the ID is wrong

The request body or query parameters failed validation.

{
  "detail": [
    {
      "loc": ["body", "url"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Common causes:

Field	Cause
`url`	Missing or not a valid URL
`label`	Missing, empty, or longer than 100 characters
`sub_org_id`	Not a valid integer or references a sub-org that does not belong to your organization

Rate limiting is enforced at the platform level. Back off and retry after the interval indicated in the Retry-After response header.

An unexpected error occurred on the server. If this error persists, contact support and include the request details and timestamp.

Always check the detail field — it provides a specific, human-readable explanation of the error.
API keys cannot manage themselves — use the web UI (Clerk session) for key management operations.
Sub-org scope errors (403) — check whether the key was created with a sub-org restriction; if so, create an org-wide key for cross-sub-org operations.
Revoked keys return 401 — if a key was working and suddenly returns 401, it may have been revoked (e.g., due to sub-org archival).
Plan downgrade — if your organization's plan was changed to Tier 1 or Tier 2, existing keys will return 403 until the plan is upgraded again.