Skip to main content

API errors

Every fremforge API error is RFC 9457 application/problem+json and carries a type URI naming the specific error:

{
  "type": "https://docs.frem.sh/reference/api/errors/seat-cap-reached",
  "title": "Payment Required",
  "status": 402,
  "detail": "Seat cap reached - add seats or enable seat overage in Org admin -> Billing."
}

Branch on type. title and detail are human-readable and may be reworded; type plus status is the stable contract.

There are 200 distinct error types.

400 Bad Request

The request was malformed, or a field failed validation.

Error type
confirm-mismatchConfirm mismatch
create-failedCreate failed
css-too-largeCss too large
digest-mismatchDigest mismatch
empty-updateEmpty update
format-mismatchFormat mismatch
ids-requiredIds required
invalid-accessInvalid access
invalid-allowed-audiencesInvalid allowed audiences
invalid-allowlistInvalid allowlist
invalid-api-keyInvalid api key
invalid-artifact-nameInvalid artifact name
invalid-artifact-versionInvalid artifact version
invalid-attestation-formatInvalid attestation format
invalid-audiencesInvalid audiences
invalid-azure-deploymentInvalid azure deployment
invalid-base-urlInvalid base url
invalid-billing-emailsInvalid billing emails
invalid-block-actionInvalid block action
invalid-block-severityInvalid block severity
invalid-bodyInvalid body
invalid-ca-keysInvalid ca keys
invalid-cidrInvalid cidr
invalid-client-idInvalid client id
invalid-commit-shaInvalid commit sha
invalid-contentInvalid content
invalid-cssInvalid css
invalid-daysInvalid days
invalid-digestInvalid digest
invalid-domainInvalid domain
invalid-emailInvalid email
invalid-enabledInvalid enabled
invalid-expected-current-seat-capInvalid expected current seat cap
invalid-expires-atInvalid expires at
invalid-featureInvalid feature
invalid-fieldInvalid field
invalid-formatInvalid format
invalid-gatesInvalid gates
invalid-git-refInvalid git ref
invalid-inputInvalid input
invalid-jsonInvalid json
invalid-labelInvalid label
invalid-max-tokensInvalid max tokens
invalid-messagesInvalid messages
invalid-modeInvalid mode
invalid-modelInvalid model
invalid-multipartInvalid multipart
invalid-nameInvalid name
invalid-patternInvalid pattern
invalid-pr-numberInvalid pr number
invalid-principal-policyInvalid principal policy
invalid-providerInvalid provider
invalid-purposeInvalid purpose
invalid-repoInvalid repo
invalid-repo-filterInvalid repo filter
invalid-repo-full-nameInvalid repo full name
invalid-requestInvalid request
invalid-require-certInvalid require cert
invalid-roleInvalid role
invalid-rules-urlInvalid rules url
invalid-run-idInvalid run id
invalid-scopeInvalid scope
invalid-scopesInvalid scopes
invalid-seat-capInvalid seat cap
invalid-seatsInvalid seats
invalid-secretInvalid secret
invalid-sinceInvalid since
invalid-slaInvalid sla
invalid-slugInvalid slug
invalid-statusInvalid status
invalid-sub-templateInvalid sub template
invalid-target-urlInvalid target url
invalid-teamInvalid team
invalid-technical-admin-emailInvalid technical admin email
invalid-temperatureInvalid temperature
invalid-tenant-slugInvalid tenant slug
invalid-termInvalid term
invalid-ttlInvalid ttl
invalid-typeInvalid type
invalid-urlInvalid url
invalid-usernameInvalid username
invalid-valueInvalid value
invalid-vendorInvalid vendor
missing-assertionMissing assertion
missing-paramsMissing params
missing-sbomMissing sbom
no-fieldsNo fields
no-scopesNo scopes
pause-failedPause failed
reason-requiredReason required
reason-too-longReason too long
reserved-prefixReserved prefix
seat-change-failedSeat change failed
too-many-eventsToo many events
too-many-idsToo many ids
too-many-messagesToo many messages
too-many-teamsToo many teams
unknown-scopeUnknown scope
unsupported-grant-typeUnsupported grant type
unsupported-spec-versionUnsupported spec version
value-too-largeValue too large

401 Unauthorized

Authentication is missing, or the credential was rejected.

Error type
authentication-requiredAuthentication required
invalid-clientInvalid client
invalid-tokenInvalid token

403 Forbidden

The credential is valid but not permitted to do this.

Error type
cross-tenantCross tenant
insufficient-scopeInsufficient scope
not-in-allowlistNot in allowlist
oauth-session-pat-mint-forbiddenOauth session pat mint forbidden
protected-accountProtected account
repo-owner-mismatchRepo owner mismatch
scope-escalationScope escalation
tenant-scope-requiredTenant scope required
user-identity-requiredUser identity required
wildcard-mint-refusedWildcard mint refused

404 Not Found

The resource does not exist - or your token cannot see it.

Error type
attempt-not-foundAttempt not found
no-active-approvalNo active approval
no-findingsNo findings
not-foundNot found
tenant-not-foundTenant not found

409 Conflict

The request conflicts with the resource’s current state.

Error type
already-acceptedAlready accepted
already-cancelledAlready cancelled
already-disabledAlready disabled
already-pausedAlready paused
already-resolvedAlready resolved
checkout-in-flightCheckout in flight
domain-verification-requiredDomain verification required
duplicate-grantDuplicate grant
duplicate-keyDuplicate key
duplicate-nameDuplicate name
duplicate-patternDuplicate pattern
duplicate-pendingDuplicate pending
internal-tenantInternal tenant
last-ownerLast owner
name-conflictName conflict
no-ca-keysNo ca keys
no-rewritesNo rewrites
no-seats-availableNo seats available
not-cancelledNot cancelled
not-cancellingNot cancelling
not-enabledNot enabled
not-enrolledNot enrolled
not-pendingNot pending
not-removedNot removed
operator-managedOperator managed
overage-frozenOverage frozen
overage-paid-plan-onlyOverage paid plan only
refund-unavailableRefund unavailable
rescan-skippedRescan skipped
seat-cap-reachedSeat cap reached
self-approveSelf approve
stale-seat-capStale seat cap
tenant-not-acceptingTenant not accepting

410 Gone

The resource existed and is permanently gone.

Error type
challenge-expiredChallenge expired
logs-purgedLogs purged

413 Payload Too Large

The body is larger than this endpoint accepts.

Error type
payload-too-largePayload too large

415 Unsupported Media Type

The request Content-Type is not supported.

Error type
unsupported-media-typeUnsupported media type

429 Too Many Requests

You have exceeded a rate limit.

Error type
rate-limitedRate limited
rate-limited-globalRate limited global

500 Internal Server Error

Something failed on our side.

Error type
db-errorDb error
insert-failedInsert failed
internalInternal
internal-errorInternal error
rate-limit-misconfiguredRate limit misconfigured
sign-failedSign failed

501 Not Implemented

Not implemented yet.

Error type
not-implemented-yetNot implemented yet

502 Bad Gateway

An upstream dependency returned an error.

Error type
approve-failedApprove failed
ci-bot-mint-failedCi bot mint failed
ci-bot-revoke-failedCi bot revoke failed
forgejo-errorForgejo error
forgejo-failedForgejo failed
forgejo-upstream-errorForgejo upstream error
install-failedInstall failed
mollie-errorMollie error
mollie-unavailableMollie unavailable
obs-put-failedObs put failed
pr-open-failedPr open failed
provisioning-failedProvisioning failed
remove-failedRemove failed
revoke-failedRevoke failed
test-failedTest failed
upstream-auth-failedUpstream auth failed
upstream-errorUpstream error
upstream-unreachableUpstream unreachable

503 Service Unavailable

A dependency is temporarily unavailable.

Error type
ai-disabledAi disabled
attestations-disabledAttestations disabled
billing-unavailableBilling unavailable
ci-bots-unavailableCi bots unavailable
forgejo-not-configuredForgejo not configured
forgejo-proxy-disabledForgejo proxy disabled
forgejo-unavailableForgejo unavailable
forgejo-unreachableForgejo unreachable
invitations-unavailableInvitations unavailable
not-configuredNot configured
ownership-unverifiableOwnership unverifiable
renovate-disabledRenovate disabled
sbom-ingest-unavailableSbom ingest unavailable
seat-change-unavailableSeat change unavailable
seat-holds-unavailableSeat holds unavailable
secrets-unavailableSecrets unavailable
siem-unavailableSiem unavailable
token-exchange-disabledToken exchange disabled