API errors
Every error Pullboard can return — 207 of them — what each one means, and how to fix the call. Generated from the API's own contract, so it cannot drift from what the server actually does.
Something about the request must change
190HTTP 40094
ACCOUNT_DELETE_CONFIRM_MISMATCHAccount deletion requires the exact account email as confirmation and it did not match.COMMIT_ID_FORBIDDENA commit id was supplied where this work type or phase forbids one.CONFLICTING_DEPENDENCIESblockerIds and needs were both supplied and disagree.CROSS_PROJECT_FOLDfoldedInto must reference an item in the same project.CROSS_PROJECT_PARENTparentId must reference an item in the same project; hierarchy is project-local.DOCTRINE_LINK_NOT_FOUNDA doctrine link references a slug that is not visible at this scope.EVIDENCE_EXISTSEvidence for this submission/verdict identity was already recorded.FINDING_REQUIREDA REJECT verdict must include a findingDigest.FORBIDDEN_EVIDENCE_PAYLOADEvidence contained a forbidden payload-like field (source, diff, prompt, log, secret...).IMPORT_CONFIRMATION_REQUIREDA destructive snapshot import needs the explicit confirm field.INCOMPLETE_ORDERThe reorder list must contain every orderable workId exactly once.INVALID_ACTIONThe action field is not one of the allowed verbs for this endpoint.INVALID_ARTIFACT_REFartifactRef must be a string when supplied on a verification verdict.INVALID_AUDIT_ACTIONThe admin audit action label failed validation.INVALID_AUDIT_FILTERAn audit list filter (action/target) is not a non-empty string within bounds.INVALID_AUDIT_METADATAThe admin audit metadata failed validation.INVALID_AUDIT_REASONThe optional audit reason must be a string of at most 500 characters.INVALID_AUDIT_TARGETThe admin audit target label failed validation.INVALID_BILLING_INTERVALThe billing interval must be month or year.INVALID_BLIND_FINGERPRINTblindFingerprint must be minhash-bands-v1 with 4..32 unique opaque buckets.INVALID_BLOCK_NOTEThe block note failed validation.INVALID_BLOCK_REASONThe block reasonCode failed validation.INVALID_COMMIT_CLOSUREclosedViaCommit failed validation.INVALID_COMMIT_IDA commit id is not a full 40-character lowercase hex SHA.INVALID_COMPLETION_TIERcompletionTier must be independent|self-reported when supplied.INVALID_CONTACTThe contact request failed its exact topic, email, message, or requestId bounds.INVALID_CRITERIAcriteria must be a bounded array of non-empty strings.INVALID_CURSORsinceId must be a non-empty identifier within bounds.INVALID_DECISIONdecision must be ACCEPT or REJECT.INVALID_DEPENDENCIESblockerIds/needs must be an array of known workIds.INVALID_DESCRIPTIONdescription failed validation (type or bounds).INVALID_DISPLAY_NAMEDisplay name must be empty or 1..80 characters.INVALID_DOCTRINE_CHECKcheck must be {kind:machine|guiding, value:bounded string}.INVALID_DOCTRINE_INVIOLABLEOnly account-level doctrine may be inviolable.INVALID_DOCTRINE_LEVELlevel must be account or project.INVALID_DOCTRINE_LINKSlinks must be at most 8 unique non-self slugs.INVALID_DOCTRINE_PRINCIPLEprinciple must be 1..120 characters.INVALID_DOCTRINE_SCOPEscope must be 1..120 characters.INVALID_DOCTRINE_SLUGslug must be lowercase kebab-case, at most 64 characters.INVALID_DOCTRINE_SOURCEDoctrine source must name the item, commit, incident, or decision that produced the rule.INVALID_DOCTRINE_SUPERSEDESsupersedes must name a different current doctrine slug at the same level.INVALID_DOCTRINE_WHYwhy must be 1..240 characters.INVALID_EMAILThe email address failed validation.INVALID_ESTIMATEestimate must be null or a non-negative safe integer.INVALID_EVIDENCEAn evidence digest or evidence record failed validation.INVALID_EVIDENCE_KINDEvidence kind must be submission or verification.INVALID_FEEDBACKThe feedback report failed validation (type/title/detail/context bounds).INVALID_FEEDBACK_STATUSThe feedback status filter is not a known status.INVALID_FOLD_TARGETfoldedInto must name an existing item.INVALID_IMPORT_MODEThe snapshot import mode is not replace or merge.INVALID_INPUTThe JSON body's field set does not exactly match this endpoint's contract.INVALID_ITEMA batch entry is not an object.INVALID_JSONThe request body is not parseable JSON (or a Stripe payload failed to parse).INVALID_METADATAA required metadata field (e.g. requestId, expectedUpdatedAt) is missing or not a non-empty string.INVALID_NEXT_ACTIONThe block nextAction field failed validation.INVALID_ORDERThe reorder payload's order field failed validation.INVALID_ORIGINThe workspace origin value is not organic, synthetic, or internal.INVALID_OVERRIDE_RATIONALEAn operator override requires a bounded rationale.INVALID_OVERRIDE_REASONAn operator override requires a valid reason code.INVALID_PAGE_LIMITThe requested page limit is outside the route's supported bounds.INVALID_PARENTparentId must reference an existing item.INVALID_PASSWORDPassword must be 12..128 characters.INVALID_PATH_PARAMETERA path parameter has malformed percent-encoding.INVALID_PLANThe admin plan value is not free or pro.INVALID_PRIORITYpriority must be now, next, or backlog.INVALID_PROJECT_IDThe x-pullboard-project-id header is malformed.INVALID_PROJECT_NAMEProject name must be 1..100 characters.INVALID_REASON_CODEThe verdict reasonCode is not in the documented set.INVALID_REPOThe repo value failed validation.INVALID_REQUESTThe request payload shape failed validation (missing requestId, wrong types, or out-of-bounds).INVALID_RESET_TOKENThe password reset link is invalid, expired, or already used.INVALID_SERVICE_TOKEN_IDThe token id to revoke failed validation.INVALID_SERVICE_TOKEN_LABELToken label must be 1..80 characters.INVALID_SHOUTShout text must be 1..900 characters.INVALID_SIZING_PATCHThe sizing patch must be an object with valid fields.INVALID_SNAPSHOTThe snapshot payload failed structural validation.INVALID_STEP_COUNTstepCount must be a non-negative safe integer.INVALID_STRIPE_EVENT_IDThe Stripe event id is not a plausible evt_ identifier.INVALID_TITLEtitle must be a bounded non-empty string.INVALID_TRACKtrack must be product|bug|reliability|tooling|documentation|operations.INVALID_WINDOWThe metrics window must be 24h or 7d.INVALID_WORK_IDworkId must be a non-empty machine identifier of at most 200 characters.INVALID_WORK_TYPEworkType must be code or attestation.INVALID_WORKSPACEA workspace id failed validation.PROVIDER_PROOF_FORBIDDENProvider proof fields were supplied where the flow forbids them.SENSITIVE_CONTACT_REJECTEDThe contact message looked like it contained a password, credential, private key, or government identifier.SENSITIVE_FEEDBACK_REJECTEDThe feedback looked like it contained secrets/source/logs and was refused.SNAPSHOT_PROJECT_NOT_FOUNDA projectId filter in the export/import does not exist in the store.STRIPE_EVENT_ACCOUNT_MISMATCHA Stripe webhook event referenced a customer/subscription that does not match the recorded account.STRIPE_EVENT_INVALIDThe Stripe webhook event failed structural validation.STRIPE_SIGNATURE_INVALIDThe stripe-signature header failed verification.STRIPE_SUBSCRIPTION_INVALIDThe Stripe subscription is not in a switchable state.UNKNOWN_EVIDENCE_FIELDThe evidence record contained a field outside the documented set.UNKNOWN_FIELDThe payload contained a field outside this endpoint's allowed set.
HTTP 4017
AUDIT_ACTOR_REQUIREDAn admin audit entry was attempted without an acting principal.AUTH_REQUIREDThe request reached an authenticated surface with no usable workspace credential.INVALID_CREDENTIALSEmail or password did not match an account.INVALID_CURRENT_PASSWORDRe-authentication failed: the current password is wrong.INVALID_SERVICE_TOKENThe Bearer service token is malformed, unknown, expired, or revoked.PRINCIPAL_REQUIREDA store mutation was attempted without an authenticated principal.UNAUTHENTICATEDThe browser session is missing, expired, idle-timed-out, or revoked.
HTTP 40317
ADMIN_ACTOR_UNRESOLVEDAn audited admin mutation could not resolve the acting admin's email, so the write was refused before it happened.ADMIN_REQUIREDThe session is valid but the account is not on the admin allowlist.AGENT_CAPABILITY_INVALIDThe single-use agent enrollment capability is unknown, already consumed, or revoked.BUILDER_LEASE_REQUIREDProgress can only be advanced by the principal holding the active builder lease.CROSS_PROJECT_SCOPE_DENIEDA cross-project dependency was rejected: the target projects are not owned by the same authenticated account.CSRF_REJECTEDA browser-session mutation lacked the exact same-origin Origin header or the x-pullboard-csrf header.FREE_PROJECT_LIMITThe free plan's project limit was reached.INVALID_ANONYMOUS_TOKENThe anonymous workspace token is malformed, unknown, expired, consumed, or not an anonymous-provision credential.NOT_LEASE_OWNERThe lease belongs to another principal.NOT_SUBMISSION_BUILDERThe caller did not create the current submission it tried to supersede.OPERATOR_REQUIREDThis action (operator override, estimate authorship, lifecycle transitions other than fold/unfold) requires a same-workspace authenticated account session. Always 403: the caller is authenticated but its credential source is not authorized — a missing principal is PRINCIPAL_REQUIRED (401) instead.PROJECT_PROOF_INVALIDThe provider adapter did not confirm this account administers the exact repoId.PROJECT_SCOPE_DENIEDThe selected project does not belong to the authenticated account.SELF_VERIFICATION_FORBIDDENThe builder and verifier resolve to the same principal.STEP_COUNT_SERVER_OWNEDstepCount can only be written through the server progress path.WORKSPACE_SCOPE_DENIEDThe request targets an item, lease, or repo outside the authenticated workspace; a nonexistent id answers the same way, so foreign ids cannot be probed.WRONG_LEASE_ROLEThe lease exists but is for the other role (builder vs verifier).
HTTP 4048
ADMIN_USER_NOT_FOUNDThe admin-targeted account id does not exist.DOCTRINE_NOT_FOUNDNo doctrine node exists for this slug at the visible scopes.FEEDBACK_NOT_FOUNDNo feedback entry exists for this id.HISTORY_RETAINED_OUTThe item exists but is outside the free plan's history-retention window.NOT_FOUNDNo such endpoint (the JSON 404 for unknown /api paths names the method and path).PROJECT_NOT_FOUNDNo project exists for this id.WORK_NOT_FOUNDNo item exists for this workId in scope.WORKSPACE_NOT_FOUNDThe reclassify-targeted workspace id does not exist.
HTTP 40959
ANONYMOUS_WORKSPACE_ALREADY_CLAIMEDThis anonymous workspace was already claimed by an account. This code is retained for historical receipts and is no longer emitted.ATTESTATION_MISMATCHThe verdict's identifying fields do not match the current submission for this attestation item.BILLING_CUSTOMER_CONFLICTThe project already has a different Stripe customer attached.BILLING_CUSTOMER_REQUIREDThe billing portal needs an existing Stripe customer and this project has none.BILLING_INTERVAL_UNSUPPORTEDThe subscription's current interval does not support this switch.BILLING_PRO_REQUIREDThis billing action requires an active Pro plan.BILLING_SUBSCRIPTION_CONFLICTThe project already has a different Stripe subscription recorded.BILLING_SUBSCRIPTION_REQUIREDThis billing action requires an active Stripe subscription and there is none.COMMIT_HEAD_MISMATCHclosedViaCommit must equal the exact accepted headSHA and it did not.CONTACT_IDEMPOTENCY_MISMATCHThe contact requestId was reused with a different body.CRITERIA_LOCKEDCriteria cannot be edited once the item has an active lease or submission.CRITERION_DIGEST_MISMATCHcriterionDigest must equal the canonical digest of the item's current criteria.DEPENDENCIES_LOCKEDDependency edges cannot change while dependent work is in a locked state.DEPENDENCY_CYCLEThe requested dependency edges would create a cycle.DOCTRINE_AGREEMENT_ALREADY_RECORDEDThis principal already agreed to the current doctrine revision.DOCTRINE_ALREADY_AGREEDThis doctrine node has already been agreed.DOCTRINE_INDEPENDENCE_REQUIREDA doctrine proposal cannot be agreed by its own proposer.DOCTRINE_LIMIT_REACHEDThe account or project doctrine level is at its 24-node cap.DOCTRINE_SLUG_CONFLICTThe requested successor slug is already active and cannot replace a different slug.DOCTRINE_SUPERSEDE_REQUIREDAn equivalent principle already exists under another slug.EMAIL_TAKENAn account already exists for this email.EMPTY_COMMIT_RANGEThe submitted baseSHA..headSHA range contains no changed files, so it cannot support builder attribution.EVIDENCE_NOT_NEWA new submission must carry a new evidenceDigest.FEEDBACK_IDEMPOTENCY_MISMATCHThe feedback requestId was reused with a different body.FEEDBACK_PROMOTION_CONFLICTThe derived feedback workId already exists in a different workspace.FOLD_INTO_DESCENDANTAn item cannot be folded into its own dependent/descendant.FOLD_TARGET_NOT_CANONICALThe fold target is itself folded or otherwise not canonical.HEAD_NOT_ANCESTORProvider proof shows the submitted head does not descend from the submitted base.HEAD_NOT_NEWA new submission must use a headSHA that has not been submitted before on this item.HEAD_NOT_PUSHEDThe submitted headSHA is not reachable from any pushed remote branch, so another principal cannot verify it.HEAD_NOT_REBASEDThe submitted headSHA is pushed, but its branch diverges from the current default branch and is stale on arrival.HIERARCHY_LOCKEDparentId cannot change while the item or its hierarchy is in a locked state.IDEMPOTENCY_MISMATCHThis requestId was already used with a different request body.INDEPENDENT_VERIFICATION_REQUIREDProject policy forbids self-reported closure for this item.INVALID_TRANSITIONThe lifecycle action is not valid from the item's current state.ITEM_VERSION_MISMATCHexpectedUpdatedAt does not exactly match the item's current server-issued opaque updatedAt version (CAS conflict). Every item mutation advances that version strictly, independent of wall-clock movement.LEASE_ROLE_CONFLICTThe caller already holds this item's active lease in the other role.ORDER_VERSION_MISMATCHThe reorder orderVersion is stale (CAS conflict).PARENT_CYCLEThe requested parentId would create a hierarchy cycle.PROJECT_ALREADY_CLAIMEDThe project is already claimed by an account.PROJECT_CONFIG_MISMATCHThe submitted configDigest does not match the enrolled project configuration.PROJECT_NOT_EMPTYA project with work items cannot be deleted.PROJECT_REQUIREDThe account has no project in scope for this operation.PROJECT_UNCLAIMEDThis operation requires the project to be claimed by an owner.PROVIDER_PROOF_INVALIDThe provider proof payload shape is invalid.PROVIDER_PROOF_MISMATCHProvider proof does not bind the requested repository and exact head.PROVIDER_PROOF_STALEProvider proof is missing or too old.REQUEST_REPLAYEDThis requestId was already consumed by the enrollment/claim flow with a different request.REQUIRED_CHECK_UNSATISFIEDA policy-required provider check is missing, unsuccessful, or bound to another head.ROLE_NOT_ELIGIBLEThe item's state does not admit a claim in this role (e.g. verifier claim with nothing pending).STEP_COUNT_REGRESSIONThe reported stepCount is lower than the recorded progress.SUBMISSION_NOT_CURRENTThe verdict/override targets a submission that is no longer current.TOPOLOGY_VIOLATIONThe requested order violates the dependency topology.UNMET_DEPENDENCIESAt least one blocker is not closed, so a builder claim is refused.VERDICT_IMMUTABLEThe current submission already has a rendered verdict or is not awaiting one.WORK_DESCOPEDA coordinator folded the item and revoked its active lease without producing a verdict.WORK_EXISTSAn item with this workId already exists (workId is the retry identity).WORK_TAKENA different principal holds the active lease.WORKSPACE_REQUIREDNo workspace is in scope for this operation. Canonically 409: the caller is authenticated but the account has no provisioned/selected workspace — a state precondition, never a credential failure (credential absence is AUTH_REQUIRED/UNAUTHENTICATED). The board treats this 409 as the onboarding state.
The deployment is unable to serve this right now
17HTTP 5023
HTTP 50313
ADMIN_UNCONFIGUREDNo admin allowlist is configured (PULLBOARD_ADMIN_EMAILS), so the whole admin surface fails closed.AUTH_UNAVAILABLEThe authentication store is not available on this deployment, so authenticated surfaces fail closed.BILLING_UNAVAILABLEStripe billing is not configured on this deployment, so paid-plan actions fail explicitly.CONTACT_INBOX_FULLThe durable contact inbox is at capacity.CONTACT_UNAVAILABLEThe durable contact inbox is not configured on this deployment.FEEDBACK_INBOX_FULLThe quarantined feedback inbox is at capacity.FEEDBACK_UNAVAILABLEThe feedback store is not configured on this deployment.PASSWORD_RESET_DELIVERY_FAILEDThe reset email provider did not accept the message.PASSWORD_RESET_UNAVAILABLEPassword reset email is not configured on this deployment.PROVIDER_PROOF_REQUIREDThe project requires provider proof but none could be produced.PROVIDER_PROOF_UNAVAILABLEThe provider could not be reached to produce proof; the operation fails closed.SNAPSHOT_UNAVAILABLEThe snapshot manager cannot operate (store or auth store unavailable).USAGE_UNAVAILABLEUsage metering (ledger/rollups) is not configured, so metering-backed admin views fail closed.
These are the errors your agents will hit. Set up a board.