Reference

Error codes

Every error code Bedrock can return, with the recovery action for each.

Error envelope

Every error response uses the same flat shape:

json

{
  "statusCode": 403,
  "error": "VULNERABILITY_SPECIALIST_REQUIRED",
  "message": "This case is flagged as vulnerable and requires a specialist reviewer or lead reviewer (FCA FG21/1)",
  "requestId": "3c1fa2d4-b1c4-4f7e-9c83-29e7f9a23b7b",
  "timestamp": "2026-04-08T12:31:04.219Z"
}

statusCode — mirrors the HTTP status line for easy access in code.
error — the specific machine-readable code. Match on this, not on the HTTP status alone; the same 403 can mean several different things.
message — a short human-readable description of what went wrong.
requestId — the server-assigned correlation id. Include this when raising support tickets.
timestamp — ISO 8601 server time of the failure.
details — optional, operation-specific structured context (present on some validation errors).

Codes

Grouped by HTTP status, then by specificity. Generic codes (BAD_REQUEST, UNAUTHORIZED, etc.) are the fallback when no more specific code applies — handle them as a safety net, match the specific codes first.

HTTP	Code	Description
`400`	`BAD_REQUEST`	The request body or parameters are malformed. Generic 400 — fix the request and retry.
`401`	`UNAUTHORIZED`	Missing or unrecognised credentials. Generic 401.
`401`	`API_KEY_MISSING`	No X-Bedrock-Key header was sent.
`401`	`API_KEY_INVALID`	The X-Bedrock-Key header does not resolve to a known firm key.
`401`	`API_KEY_REVOKED`	The key exists but has been revoked.
`401`	`TOKEN_INVALID`	A JWT (NextAuth session token) failed verification.
`403`	`FORBIDDEN`	Credentials are valid but the scope is insufficient. Generic 403.
`403`	`PLAN_INSUFFICIENT`	The firm’s plan does not include the attempted operation (e.g. Principal-only on a Ledger-only subscription).
`403`	`VULNERABILITY_SPECIALIST_REQUIRED`	A reviewer without the FG21/1 specialist flag attempted to pick up a job carrying vulnerability flags. Only specialist or lead reviewers can handle flagged cases.
`403`	`SENIOR_SIGN_OFF_REQUIRED`	A reviewer without LEAD_REVIEWER or FIRM_ADMIN role attempted to complete a job flagged as requiring senior sign-off.
`404`	`NOT_FOUND`	No resource found for the given identifier. Generic 404.
`404`	`USER_NOT_FOUND`	The user ID or email does not exist inside the firm.
`404`	`ADMIN_NOT_FOUND`	The Bedrock staff account does not exist. Used by the admin app only.
`404`	`DOCUMENT_NOT_FOUND`	The uploaded advice document could not be read from storage. Upload the document first before submitting the job.
`409`	`CONFLICT`	The request collides with current server state. Usually a uniqueness violation — see the message for which field.
`409`	`IMPACT_ASSESSMENT_REQUIRED`	POST /v1/principal/jobs supplied a modelProvider/modelVersion with no matching APPROVED impact assessment on file. Applies only when the firm has the enforceImpactAssessments gate on (default).
`422`	`CHECKLIST_INCOMPLETE`	A reviewer attempted to submit a decision before completing all mandatory checklist items.
`429`	`RATE_LIMITED`	Per-key rate limit exceeded. Honour the Retry-After header.
`500`	`INTERNAL_ERROR`	Unexpected server-side failure. Reported internally; see requestId in the response for correlation.
`503`	`CHAIN_INTEGRITY_FAILED`	The firm chain failed an integrity check; writes are paused until resolved.

Retry guidance

4xx — fix the request and retry. Don't loop blindly.
429 — sleep for the value of Retry-After, then retry.
5xx — exponential backoff with jitter, capped at 1 minute, capped at 5 attempts.