Failed requests return a JSON envelope with a human-readable error and a stable
machine-readable code. Branch on code, not on the message text.
{
"success": false,
"error": "Human-readable message",
"code": "ERROR_CODE"
}
Validation (400)
Code
Meaning
(various)
Validation error - see the error message for details
INVALID_ROLE
Org/event role value not in the allowed list (must be UPPERCASE)
INVALID_COMPANY_TYPE
company_type not in the allowlist
INVALID_SIZE_BAND
size_band not in the allowlist
INVALID_ORG_ID / INVALID_USER_ID
UUID format check failed
INSUFFICIENT_PERMISSIONS
Role hierarchy violation (e.g. ADMIN cannot promote someone to OWNER)
MISSING_FIELDS
Required body field absent
TOO_EARLY / TOO_LATE
Check-in attempted outside the window
NO_TEAM
Milestone gate: participant must join a team first
INVALID_EMAIL(v2.0)
Participant email missing or malformed
INVALID_NAME(v2.0)
Team name fails length / character validation
INVALID_PROBLEM(v2.0)
Team problem text exceeds 500 chars
INVALID_STATUS(v2.0)
Team recruitingStatus not one of the allowed values
INVALID_FIELDS(v2.0)
Mass-assignment attempt on protected team fields
INVALID_JUDGES(v2.0)
One or more user IDs lack the JUDGE role
NOT_JUDGE(v2.0)
Single assignment target user lacks JUDGE role
TARGET_TRACK_REQUIRED(v2.0)
Track move body missing targetTrackId
INVALID_TRACK(v2.0)
Target track does not belong to this super event
Authentication & authorization (401 / 402 / 403)
HTTP
Code
Meaning
401
INVALID_API_KEY
Key missing, invalid, revoked, or expired
402
EVENT_NOT_PAID
Cannot accept registrations until the super event is paid (Stripe Checkout)
403
FORBIDDEN
The endpoint or resource isn’t available to your key
403
INSUFFICIENT_SCOPE
Key does not include the required scope
403
ORGANIZER_REQUIRED
Manual check-in requires an organizer key
403
ADMIN_REQUIRED
Operation requires OWNER or ADMIN org role
403
NOT_ACCEPTED
Registration status is not accepted
403
PERMISSION_DENIED
Operation requires a specific role
403
NOT_ORG_MEMBER
Caller not a member of the target org
403
ORGANIZER_CANNOT_REGISTER
Organizers can’t register for their own event (returned by the deprecated POST /events/:eventId/register)
Not found (404)
Code
Meaning
INVALID_TOKEN
Check-in token not found
USER_NOT_FOUND
Target user does not exist in BuilderBase
REG_NOT_FOUND
Registration not found
NOT_FOUND
The super event, event, team, submission, registration or check-in point named in the URL doesn’t exist. A resource that exists but belongs to another organization returns 403 FORBIDDEN instead, and so does an unknown organization in an /organizations/:id path.
TEAM_NOT_FOUND(v2.0)
Team does not exist or has been deleted
TRACK_NOT_FOUND(v2.0)
Track not in this super event
ASSIGNMENT_NOT_FOUND(v2.0)
Judge assignment ID does not exist
BUILDER_NOT_FOUND(v2.0)
Participant has no accepted super-event registration
Conflict (409)
Code
Meaning
DUPLICATE_MEMBER
User is already a member of this org
REGISTRATION_CLOSED(v2.0)
Super event registration is closed
MAX_PARTICIPANTS_REACHED(v2.0)
Cap hit; body includes acceptedCount + maxParticipants
