Postconditions: what we check

• repos.get · github-repo-get-no-try-catch

  error
  Whenoctokit.repos.get() called without try-catch
  ThrowsRequestError with status 404 (not found), 403 (forbidden), 401 (unauthorized)
  Required handlingMUST wrap await octokit.repos.get() in try-catch block. Catch block should check error.status for specific error codes: 404 (repo not found/private), 403 (rate limit or permission denied), 401 (auth failed). Handle each case appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• repos.create · github-repo-create-no-try-catch

  error
  Whenoctokit.repos.create() called without try-catch
  ThrowsRequestError with status 422 (validation failed), 403 (forbidden), 401 (unauthorized)
  Required handlingMUST wrap await octokit.repos.create() in try-catch block. Check error.status to distinguish: 422 (validation error - check error.message for details), 403 (quota/permission issue), 401 (authentication failure).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• repos.update · github-repo-update-no-try-catch

  error
  Whenoctokit.repos.update() called without try-catch
  ThrowsRequestError with status 404 (not found), 403 (forbidden), 422 (validation failed)
  Required handlingMUST wrap await octokit.repos.update() in try-catch block. Handle 404 (repo not found), 403 (insufficient permissions), 422 (invalid parameters).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• repos.delete · github-repo-delete-no-try-catch

  error
  Whenoctokit.repos.delete() called without try-catch
  ThrowsRequestError with status 404 (not found), 403 (forbidden), 401 (unauthorized)
  Required handlingMUST wrap await octokit.repos.delete() in try-catch block. Always verify repository exists before deletion. Handle 403 (verify admin permissions), 404 (already deleted or never existed), 401 (auth issue).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• git.getRef · github-git-getref-no-try-catch

  error
  Whenoctokit.git.getRef() called without try-catch
  ThrowsRequestError with status 404 (ref not found), 403 (forbidden), 401 (unauthorized)
  Required handlingMUST wrap await octokit.git.getRef() in try-catch block. 404 errors are common and expected (ref doesn't exist), so handle gracefully. Also handle 403 (private repo or rate limit) and 401 (auth failure).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• git.createRef · github-git-createref-no-try-catch

  error
  Whenoctokit.git.createRef() called without try-catch
  ThrowsRequestError with status 422 (ref already exists), 404 (repo not found), 403 (forbidden)
  Required handlingMUST wrap await octokit.git.createRef() in try-catch block. Handle 422 (ref already exists - check if this is acceptable), 404 (repo doesn't exist), 403 (no write access). Consider checking if ref exists first with git.getRef().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• pulls.create · github-pull-create-no-try-catch

  error
  Whenoctokit.pulls.create() called without try-catch
  ThrowsRequestError with status 422 (validation failed), 403 (forbidden), 404 (repo not found)
  Required handlingMUST wrap await octokit.pulls.create() in try-catch block. Check error.status and error.message: 422 can indicate "No commits between base and head", "Head ref doesn't exist", or "A pull request already exists". Handle each case appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• pulls.merge · github-pull-merge-no-try-catch

  error
  Whenoctokit.pulls.merge() called without try-catch
  ThrowsRequestError with status 405 (not mergeable), 404 (not found), 403 (forbidden)
  Required handlingMUST wrap await octokit.pulls.merge() in try-catch block. Before merging, check PR mergeable state. Handle 405 (check error.message for specific reason: conflicts, required checks, already merged), 404 (PR not found), 403 (no permission).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• pulls.list · github-pull-list-no-try-catch

  warning
  Whenoctokit.pulls.list() called without try-catch
  ThrowsRequestError with status 404 (repo not found), 403 (forbidden), 422 (invalid params)
  Required handlingSHOULD wrap await octokit.pulls.list() in try-catch block. Handle 404 (repo not found or private), 403 (check rate limit headers), 422 (validate query parameters).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• issues.create · github-issue-create-no-try-catch

  error
  Whenoctokit.issues.create() called without try-catch
  ThrowsRequestError with status 422 (validation failed), 403 (forbidden), 404 (repo not found), 410 (issues disabled)
  Required handlingMUST wrap await octokit.issues.create() in try-catch block. Handle 422 (validation - check error.message for details), 403 (no permission), 404 (repo not found), 410 (issues disabled - direct user to discussions or PRs instead).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• issues.update · github-issue-update-no-try-catch

  error
  Whenoctokit.issues.update() called without try-catch
  ThrowsRequestError with status 404 (not found), 403 (forbidden), 422 (validation failed), 410 (issues disabled)
  Required handlingMUST wrap await octokit.issues.update() in try-catch block. Handle 404 (issue not found), 403 (check if issue is locked or user lacks permission), 422 (invalid update parameters), 410 (issues disabled).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• issues.list · github-issue-list-no-try-catch

  warning
  Whenoctokit.issues.list() called without try-catch
  ThrowsRequestError with status 404 (repo not found), 403 (forbidden), 422 (invalid params)
  Required handlingSHOULD wrap await octokit.issues.list() in try-catch block. Handle 404 (repo not found or private), 403 (check rate limit headers), 422 (validate filter/sort parameters).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• repos.createOrUpdateFileContents · github-file-update-no-try-catch

  error
  Whenoctokit.repos.createOrUpdateFileContents() called without try-catch
  ThrowsRequestError with status 404 (repo/branch not found), 409 (conflict), 422 (validation failed)
  Required handlingMUST wrap await octokit.repos.createOrUpdateFileContents() in try-catch block. Handle 409 (concurrent modification - fetch latest SHA and retry), 404 (verify repo and branch exist), 422 (validate commit message and content encoding).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[13]
• repos.getContent · github-get-content-no-try-catch

  error
  Whenoctokit.repos.getContent() called without try-catch
  ThrowsRequestError with status 404 (not found), 403 (forbidden), 403 (too large)
  Required handlingMUST wrap await octokit.repos.getContent() in try-catch block. Handle 404 (path not found - this is often expected behavior for existence checks), 403 with "too large" (use git.getBlob() for large files), 403 for other reasons (auth/rate limit).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[14]
• search.repos · search-repos-rate-limit

  error
  Whenoctokit.search.repos() called without try-catch and rate limit (HTTP 403/429) is hit from exceeding 30 authenticated or 10 unauthenticated requests/minute
  ThrowsRequestError with status 403 (rate limit exceeded) or 429 (secondary rate limit). Response headers include x-ratelimit-remaining: 0 and x-ratelimit-reset. Secondary rate limits are undocumented but trigger at rapid burst patterns.
  Required handlingMUST wrap await octokit.search.repos() in try-catch. Check error.status === 403 and error.response?.headers['x-ratelimit-remaining'] === '0' for rate limit. Implement exponential backoff. Consider @octokit/plugin-throttling plugin.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15]
• search.repos · search-repos-validation-error

  warning
  Whenoctokit.search.repos() called with query exceeding 256 characters or more than 5 AND/OR/NOT operators, or querying inaccessible resources
  ThrowsRequestError with status 422 (Validation failed). Also 503 (Service Unavailable) when query times out server-side.
  Required handlingMUST wrap in try-catch. Validate query length (<256 chars) before calling. Handle 422 (invalid query — show user a helpful error), 503 (search timeout — retry with simpler query).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15]
• search.code · search-code-auth-required

  error
  Whenoctokit.search.code() called without authentication or with invalid token
  ThrowsRequestError with status 401 (Requires authentication) for unauthenticated requests. Code search requires authentication — unlike other search endpoints.
  Required handlingMUST wrap in try-catch. Handle 401 (missing/invalid auth — check token configuration), 403 (rate limit — 9/min limit is easy to hit), 422 (invalid query syntax). Verify octokit instance has auth token before calling.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15]
• search.issuesAndPullRequests · search-issues-rate-limit

  error
  Whenoctokit.search.issuesAndPullRequests() called without try-catch and hits 30/min rate limit or 10/min semantic search limit
  ThrowsRequestError with status 403 or 429 (rate limit exceeded).
  Required handlingMUST wrap in try-catch. Implement exponential backoff on 403/429. Check x-ratelimit-remaining headers. Consider using octokit.paginate() with throttling plugin for bulk operations.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15]
• git.createCommit · git-create-commit-not-found

  error
  Whenoctokit.git.createCommit() called without try-catch and the repo, tree SHA, or parent commit SHA does not exist
  ThrowsRequestError with status 404 (Not Found) when owner/repo does not exist or the token lacks access. RequestError with status 409 (Conflict) when parent commit references are invalid or SHA collision.
  Required handlingMUST wrap in try-catch. Handle 404 (repo not found or no access), 409 (conflict — re-fetch latest commit SHA and retry), 422 (validation — check tree SHA is valid). Always use the latest commit SHA as parent to avoid conflicts.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• git.createTree · git-create-tree-invalid-sha

  error
  Whenoctokit.git.createTree() called without try-catch when base_tree SHA or blob SHAs in tree items are invalid or not found in the repository
  ThrowsRequestError with status 404 (Not Found) when repo or base_tree SHA not found. RequestError with status 422 (Validation Failed) when tree items contain invalid modes, invalid SHAs, or exceed GitHub's file size limits.
  Required handlingMUST wrap in try-catch. Validate blob SHAs come from the same repository. Handle 404 (base_tree not found — use current HEAD SHA), 422 (invalid tree items — check file modes: 100644, 100755, 040000, 160000, 120000).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17]
• git.createBlob · git-create-blob-error

  error
  Whenoctokit.git.createBlob() called without try-catch when repo not found, token lacks write access, or content exceeds file size limits
  ThrowsRequestError with status 403 (Forbidden — no write access or file too large for blob API — use uploads for files > 100MB). Status 404 (Not Found — repo or owner not found). Status 422 (Validation Failed).
  Required handlingMUST wrap in try-catch. Handle 403 (check token has contents:write scope), 404 (verify repo owner/name), 422 (validate base64 encoding and file size).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• git.updateRef · git-update-ref-non-fast-forward

  error
  Whenoctokit.git.updateRef() called without try-catch when the ref has been updated by another process (non-fast-forward update) or ref doesn't exist
  ThrowsRequestError with status 422 (Unprocessable Entity) for non-fast-forward updates when force is not set. Status 404 (Not Found) when ref doesn't exist. Status 409 (Conflict) in some concurrency scenarios.
  Required handlingMUST wrap in try-catch. Handle 422 (non-fast-forward — re-fetch HEAD, re-create tree/commit on top of new HEAD, retry). Handle 404 (ref not found — check branch name). This function MUST be wrapped or commit pipelines lose data.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]
• checks.create · checks-create-not-github-app

  error
  Whenoctokit.checks.create() called without try-catch and the octokit instance uses OAuth token or PAT instead of GitHub App authentication
  ThrowsRequestError with status 403 (Forbidden). OAuth apps and personal access tokens (classic) cannot use this endpoint — only GitHub App installations can create check runs. GitHub Apps need the checks:write permission.
  Required handlingMUST wrap in try-catch. Handle 403 (verify using GitHub App installation token, not PAT/OAuth — check authentication method and checks:write permission). Handle 404 (repo not found), 422 (invalid check run parameters: invalid conclusion value, missing name/head_sha).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• checks.update · checks-update-invalid-transition

  warning
  Whenoctokit.checks.update() called without try-catch with an invalid status transition or conclusion value, or non-App authentication
  ThrowsRequestError with status 403 (non-App auth) or 422 (invalid conclusion/status combination — e.g., setting status to "waiting"/"pending"/"requested" which is only allowed for GitHub Actions, not Apps).
  Required handlingMUST wrap in try-catch. Handle 403 (App auth required), 404 (check run not found — verify check_run_id), 422 (invalid status for App context — only use queued/ in_progress/completed with valid conclusion values like success/failure/neutral).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• actions.createWorkflowDispatch · workflow-dispatch-no-trigger

  error
  Whenoctokit.actions.createWorkflowDispatch() called without try-catch when the workflow file lacks a workflow_dispatch: trigger or when repo/workflow not found
  ThrowsRequestError with status 404 (Not Found) when the workflow file does not exist or does not have a workflow_dispatch trigger defined. Also 422 when the ref (branch/tag) does not exist.
  Required handlingMUST wrap in try-catch. Handle 404 (workflow not found or lacks workflow_dispatch trigger — verify .github/workflows/<file>.yml has workflow_dispatch: trigger), 422 (invalid ref or input keys not defined in workflow), 403 (no actions:write permission).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• repos.createRelease · create-release-tag-not-found

  error
  Whenoctokit.repos.createRelease() called without try-catch when tag doesn't exist, discussion_category_name is invalid, or secondary rate limit triggered
  ThrowsRequestError with status 404 (Not Found) when discussion_category_name is invalid. Status 422 (Validation Failed) when tag_name conflicts or validation fails. Secondary rate limit (403) from creating content too quickly.
  Required handlingMUST wrap in try-catch. Handle 404 (invalid discussion category — validate or omit discussion_category_name), 422 (tag conflict — check if release already exists for tag), 403 secondary rate limit (add delay between release creation and asset upload steps).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• repos.createDeployment · create-deployment-conflict

  error
  Whenoctokit.repos.createDeployment() called without try-catch when required status checks have not passed or a merge conflict exists
  ThrowsRequestError with status 409 (Conflict) when required status check contexts haven't succeeded or there's a merge conflict preventing the deployment. Status 422 (Validation Failed) when endpoint is spammed.
  Required handlingMUST wrap in try-catch. Handle 409 (check error.message — "required contexts" haven't passed: either set required_contexts: [] to bypass or wait for CI), 422 (validation), 202 response (not an error — auto-merge in progress, poll for completion). Always check error.message for actionable info on 409.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23]
• repos.createDeploymentStatus · create-deployment-status-not-found

  error
  Whenoctokit.repos.createDeploymentStatus() called without try-catch when the deployment_id doesn't exist in the repository
  ThrowsRequestError with status 404 (Not Found) when deployment_id is invalid, or the deployment was deleted. Status 422 (Validation Failed) for invalid state values.
  Required handlingMUST wrap in try-catch. Store deployment_id immediately after createDeployment(). Handle 404 (deployment deleted — log and skip status update), 422 (invalid state — only use: error/failure/inactive/in_progress/queued/pending/success).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• repos.createCommitStatus · create-commit-status-not-found

  warning
  Whenoctokit.repos.createCommitStatus() called without try-catch when the commit SHA doesn't exist or token lacks repo:status scope
  ThrowsRequestError with status 404 (Not Found) when owner/repo doesn't exist or commit SHA is not found. Status 422 (Validation Failed) when state is not one of pending/success/failure/error.
  Required handlingSHOULD wrap in try-catch. Handle 404 (invalid SHA — use full 40-char SHA, verify commit exists), 422 (invalid state — only use pending/success/failure/error), 403 (token lacks repo:status scope).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25]
• pulls.get · pulls-get-not-found

  warning
  Whenoctokit.pulls.get() called without try-catch when pull_number doesn't exist or token lacks repo access
  ThrowsRequestError with status 404 (Not Found) when PR doesn't exist, was converted to draft, or token lacks access to the private repository.
  Required handlingSHOULD wrap in try-catch. Handle 404 (PR not found — may be normal in webhook processors if PR was deleted), 403 (no access to private repo).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[26]
• pulls.requestReviewers · pulls-request-reviewers-invalid

  warning
  Whenoctokit.pulls.requestReviewers() called without try-catch when reviewers are not collaborators, team doesn't exist, or PR is already closed/merged
  ThrowsRequestError with status 422 (Unprocessable Entity) when a requested reviewer is not a collaborator on the repo, or team_slugs contains a non-existent team. Also 422 when requesting review from the PR author.
  Required handlingSHOULD wrap in try-catch. Handle 422 (invalid reviewer — check error.message for which user/team is invalid, verify collaborator status before requesting), 404 (PR not found), 403 (no write access).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[27]
• issues.createComment · issues-create-comment-not-found

  error
  Whenoctokit.issues.createComment() called without try-catch when issue/PR doesn't exist, is locked, or issues are disabled for the repository
  ThrowsRequestError with status 404 (Not Found) when issue_number doesn't exist. Status 403 (Forbidden) when issue is locked. Status 410 (Gone) when issues are disabled for the repository.
  Required handlingMUST wrap in try-catch. Handle 403 (issue locked — log and skip silently), 404 (issue/PR not found — may have been deleted), 410 (issues disabled for repo — fallback to PR comment API for PRs). Check error.status and handle each case gracefully.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[28]
• issues.addLabels · issues-add-labels-not-found

  warning
  Whenoctokit.issues.addLabels() called without try-catch when a label doesn't exist in the repository or the issue doesn't exist
  ThrowsRequestError with status 404 (Not Found) when the issue_number doesn't exist or when a label in the labels array doesn't exist in the repository. Status 410 (Gone) when issues are disabled.
  Required handlingSHOULD wrap in try-catch. Handle 404 (label not found — create the label first with issues.createLabel(), or verify label exists), 410 (issues disabled), 403 (no write access). Consider creating required labels as part of repo setup.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[29]
• users.getAuthenticated · users-get-authenticated-no-auth

  error
  Whenoctokit.users.getAuthenticated() called without try-catch when the token is invalid, expired, or revoked
  ThrowsRequestError with status 401 (Requires authentication) when called without an auth token. Status 403 (Forbidden) when the token has insufficient scope (fine-grained tokens without user read permission).
  Required handlingMUST wrap in try-catch. Handle 401 (no/invalid token — check GITHUB_TOKEN env var or token rotation), 403 (insufficient scope — verify token has required scopes for your use case). Log the error and exit gracefully.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[30]
• orgs.getMembershipForUser · org-membership-not-found

  warning
  Whenoctokit.orgs.getMembershipForUser() called without try-catch when the user is not a member, org doesn't exist, or token lacks org:read permission
  ThrowsRequestError with status 404 (Not Found) when the user is not a member of the organization. Status 403 (Forbidden) when the token lacks permission to view organization membership.
  Required handlingMUST wrap in try-catch. Treat 404 as "user is not a member" (not an error). Handle 403 (token lacks org read permission — request read:org scope), 404 (not a member — return false/deny access). Do NOT re-throw 404 errors from membership checks — they are expected non-member responses.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[31]
• paginate · paginate-rate-limit

  error
  Whenoctokit.paginate() called without try-catch on a large list that requires many pages, hitting the rate limit mid-pagination
  ThrowsRequestError with status 403 (Forbidden) or 429 (Too Many Requests) when the pagination exceeds the rate limit mid-traversal. The partial results accumulated so far are lost when the error is thrown.
  Required handlingMUST wrap in try-catch. Use @octokit/plugin-throttling to automatically handle rate limits during pagination. Handle 403 (rate limit — check x-ratelimit-remaining, back off and resume). Consider using octokit.paginate.iterator() for streaming to process pages as they arrive.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[32]
• pulls.createReview · pulls-create-review-no-try-catch

  error
  Whenoctokit.pulls.createReview() called without try-catch when the PR is not found, the review body violates spam detection, or permission is insufficient
  ThrowsRequestError with status 403 (Forbidden — insufficient permissions or non-collaborator attempting to review), 404 (Not Found — PR or repo not found), 422 (Validation Failed — invalid event type, comment body violates spam detection, or endpoint has been spammed too rapidly).
  Required handlingMUST wrap in try-catch. Handle 403 (check token has pull-requests:write scope), 404 (verify PR number and repo owner/name), 422 (invalid event type — only PENDING/APPROVE/REQUEST_CHANGES/COMMENT are valid; backoff if spam detection hit).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[33]
• pulls.submitReview · pulls-submit-review-wrong-state

  error
  Whenoctokit.pulls.submitReview() called without try-catch when the review is not in PENDING state, the review ID is invalid, or event parameter is missing
  ThrowsRequestError with status 422 (Validation Failed — review is not PENDING, event parameter is blank/invalid, or endpoint has been spammed), 404 (Not Found — review_id or pull_number not found in repository).
  Required handlingMUST wrap in try-catch. Handle 422 (verify review is in PENDING state before submitting — use pulls.getReview() to check; ensure event parameter is provided). Handle 404 (verify review_id and pull_number exist). Track review state to avoid double-submit on retry.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[33]
• repos.uploadReleaseAsset · release-asset-duplicate-filename

  error
  Whenoctokit.repos.uploadReleaseAsset() called without try-catch when an asset with the same filename already exists on the release
  ThrowsRequestError with status 422 (Unprocessable Entity) when a file with the same name is already attached to the release. GitHub does not overwrite — the duplicate upload fails. Must delete the existing asset first.
  Required handlingMUST wrap in try-catch. Handle 422 (check if asset already exists with repos.listReleaseAssets(), delete it with repos.deleteReleaseAsset() before re-uploading). Handle 404 (verify release_id from createRelease response). Note: filename must match the Content-Type header; GitHub renames files with special characters automatically.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[34]
• repos.addCollaborator · add-collaborator-emu-account

  warning
  Whenoctokit.repos.addCollaborator() called without try-catch when the target user is an Enterprise Managed User (EMU) being added to a non-enterprise repository, or validation fails due to invalid permission level
  ThrowsRequestError with status 422 (Validation Failed) when an EMU account is invited to a repository in an enterprise with personal user accounts, or when the assigned permission level is below the organization's base permission. Status 403 (Forbidden) when the authenticated user lacks admin access to the repository.
  Required handlingMUST wrap in try-catch. Handle 422 (check for EMU constraints if your org uses GitHub Enterprise; verify permission level is not below org base permission). Handle 403 (verify authenticated user has admin role on the repository). Note: 201 means invitation sent; 204 means user was already a collaborator. Check the response status to distinguish.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[35]
• repos.createWebhook · create-webhook-invalid-config

  error
  Whenoctokit.repos.createWebhook() called without try-catch when the webhook URL is unreachable/malformed, or the repository does not exist
  ThrowsRequestError with status 422 (Validation Failed) when the webhook URL is malformed, uses a disallowed scheme, or points to a GitHub-internal address. Status 403 (Forbidden) when the authenticated user lacks admin access to the repository. Status 404 (Not Found) when the repository doesn't exist.
  Required handlingMUST wrap in try-catch. Handle 422 (validate URL is publicly reachable HTTPS endpoint; check for localhost/private IP disqualifiers). Handle 403 (verify token has admin:repo_hook scope or the GitHub App has the Webhooks read-write permission). Handle 404 (verify repo owner and name before attempting webhook creation).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[36]
• repos.createFork · create-fork-async-not-awaited

  warning
  Whenoctokit.repos.createFork() response is used immediately after the call without waiting for the async fork process to complete
  ThrowsDoes not throw, but the fork's git objects are not immediately available. Subsequent git operations on the fork (clone, push) within seconds of the 202 response may fail. For forks taking > 5 minutes, GitHub Support must be contacted.
  Required handlingMUST wrap in try-catch. Handle 403 (permission denied or forking disabled for org), 422 (fork already exists for this user — check if target fork already exists), 400 (invalid parameters). After successful 202, wait before using the fork: implement exponential backoff polling of repos.get() on the fork to confirm availability before proceeding.
  costmediumin prodsilent failureusers seedegraded performancevisibilityvisible
  Sources[37]
• git.createTag · git-create-tag-without-create-ref

  warning
  Whenoctokit.git.createTag() called without a subsequent git.createRef() call to make the tag reference visible, or called without try-catch
  ThrowsRequestError with status 422 (Validation Failed) when the SHA of the tagged object is invalid or references a non-existent object. Status 409 (Conflict) for concurrency issues during tag creation.
  Required handlingMUST wrap in try-catch. Handle 422 (invalid SHA — verify the object SHA exists in the repo before tagging), 409 (retry with backoff for concurrency conflicts). IMPORTANT: Always follow createTag() with git.createRef('refs/tags/<name>', sha) using the sha from the createTag response to make the tag visible.
  costmediumin prodsilent failureusers seedegraded performancevisibilityvisible
  Sources[38]
• git.deleteRef · git-delete-ref-default-branch

  error
  Whenoctokit.git.deleteRef() called without try-catch when the ref is the default branch, the ref format is invalid, or concurrency conflict occurs
  ThrowsRequestError with status 422 (Validation Failed) when attempting to delete the repository's default branch (GitHub blocks this), when the ref format is wrong (must be 'heads/<name>' not 'refs/heads/<name>'), or spam detection triggers. Status 409 (Conflict) for concurrent deletion attempts.
  Required handlingMUST wrap in try-catch. Handle 422 (check ref is not default branch — compare with repos.get().default_branch before deleting; ensure ref format is 'heads/<name>' not 'refs/heads/<name>'). Handle 409 (retry with backoff). Note: 404 is NOT returned for missing refs — use git.getRef() first to verify existence if needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]
• actions.cancelWorkflowRun · cancel-workflow-run-terminal-state

  warning
  Whenoctokit.actions.cancelWorkflowRun() called without try-catch when the workflow run is already in a terminal state (completed, cancelled, failed, timed_out)
  ThrowsRequestError with status 409 (Conflict) when the workflow run cannot be cancelled because it has already reached a terminal state. The 202 success response means cancellation was ACCEPTED, not that it has completed.
  Required handlingMUST wrap in try-catch. Handle 409 (workflow is already in a terminal state — check run status with actions.getWorkflowRun() before cancelling; treat 409 as success if the goal is to ensure the run is not running). Handle 404 (run_id not found — verify run exists). Poll actions.getWorkflowRun() after 202 to confirm cancellation completes.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[39]
• pulls.update · pulls-update-invalid-base

  warning
  Whenoctokit.pulls.update() called without try-catch when setting the base to a non-existent branch, updating a merged PR's state, or lacking write permissions
  ThrowsRequestError with status 422 (Validation Failed) when the new base branch does not exist in the repository, when attempting to reopen a merged PR (merged PRs cannot be reopened), or when validation fails on the body/title parameters. Status 403 (Forbidden) when the token lacks pull-requests:write permission.
  Required handlingMUST wrap in try-catch. Handle 422 (verify base branch exists before retargeting; check PR is not in merged state before changing state). Handle 403 (verify token has pull-requests:write scope). Handle 404 (verify PR number and repo).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[26]
• apps.createInstallationAccessToken · apps-create-installation-token-no-try-catch

  error
  Whenoctokit.apps.createInstallationAccessToken() called without try-catch when the JWT used to authenticate is expired, the App's private key has been rotated, the installation has been suspended, or the installation_id is invalid.
  ThrowsRequestError with status 401 (Bad credentials) when the JWT is expired (JWTs are valid for 10 minutes max), malformed, or signed with a rotated private key. Status 403 (Forbidden) when the installation has been suspended or the App has been blocked by the org. Status 404 (Not Found) when the installation_id does not exist or is no longer accessible to this App. Status 422 when requested permissions exceed those granted to the installation.
  Required handlingMUST wrap in try-catch. Handle 401 (mint a fresh JWT and retry once; if it persists, surface a config error to alert that the App private key is invalid or rotated). Handle 403 (do NOT retry; surface to the customer that their installation is suspended). Handle 404 (treat as uninstall; remove the org from the database and stop scheduled jobs against it). Handle 422 (surface as a permissions mismatch; do not loop). Never silently swallow.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[40][41]
• repos.compareCommitsWithBasehead · repos-compare-commits-basehead-no-try-catch

  error
  Whenoctokit.repos.compareCommitsWithBasehead() called without try-catch when either ref does not exist, the diff exceeds GitHub's response limits, or the token lacks read access to the repository.
  ThrowsRequestError with status 404 (Not Found) when one of the refs in the basehead parameter (format "{base}...{head}") does not exist in the repo, when the repo is private and the token lacks access, or when the repo was renamed/transferred. Status 422 (Unprocessable Entity) when the basehead format is invalid or the two refs are not comparable (different unrelated history). Status 403 with a rate-limit message when the diff is too large; GitHub caps the response at 300 files / 1MB and very large monorepo diffs can hit this.
  Required handlingMUST wrap in try-catch. Handle 404 (verify both refs still exist; a deleted or force-pushed branch will not be re-fetchable, so surface a clean error to the bot rather than retrying). Handle 422 (verify basehead is "{base}...{head}" and both refs share history). Handle large-diff 403 by falling back to paginated fetch with per_page=100 and assembling the file list across pages.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[42]
• issues.removeLabel · issues-remove-label-no-try-catch

  warning
  Whenoctokit.issues.removeLabel() called without try-catch when the label is not currently attached to the issue (race with concurrent automations), when the issue has been locked or moved, or when the token lacks issues:write.
  ThrowsRequestError with status 404 (Not Found) when the named label is not currently applied to the issue. This is the dominant failure mode in multi-bot environments where two automations race to remove the same label. Status 410 (Gone) when the issue has been deleted. Status 403 (Forbidden) when the token lacks issues:write scope or the repository has issues disabled. Status 301 (Moved Permanently) when the repo has been renamed and the client did not follow the redirect.
  Required handlingMUST wrap in try-catch. Treat 404 as a no-op (the label is already gone; the desired end state is satisfied). Handle 410 by removing the issue from the work queue (it is deleted). Handle 403 by surfacing a permissions error rather than retrying. Never silently swallow 5xx.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[43]
• pulls.dismissReview · pulls-dismiss-review-no-try-catch

  warning
  Whenoctokit.pulls.dismissReview() called without try-catch when the review is not in a dismissable state (already dismissed, or is a PENDING review by another reviewer), the PR is closed/merged, or the token lacks pull-requests:write.
  ThrowsRequestError with status 422 (Unprocessable Entity) when the review is already in DISMISSED state, is PENDING (only the author can dismiss their own pending review), or when dismissing would violate branch protection rules that require a re-review. Status 403 (Forbidden) when the token lacks pull-requests:write or when branch protection prohibits dismissals from non-admins. Status 404 (Not Found) when the review_id does not exist or the PR has been deleted from a force-deleted branch.
  Required handlingMUST wrap in try-catch. Treat 422 as a no-op when the review is already DISMISSED (desired state reached). Surface 403 to the operator rather than retrying; it indicates a branch-protection policy mismatch that needs manual review. Handle 404 by skipping the PR. Never silently swallow.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[44]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.