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.
"error": "Human-readable message",
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 |
Not found (404)
| Code | Meaning |
|---|
INVALID_TOKEN | Check-in token not found |
POINT_NOT_FOUND | Check-in point not found |
USER_NOT_FOUND | Target user does not exist in BuilderBase |
REG_NOT_FOUND | Registration not found |
ORG_NOT_FOUND / EVENT_NOT_FOUND / SUPER_EVENT_NOT_FOUND | Resource not found |
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 |
NO_TRACKS (v2.0) | Super event has no tracks (invite FK requirement) |
| (no code) | Duplicate (already registered / duplicate invite / duplicate check-in) |
Rate limit & server (429 / 500)
| HTTP | Code | Meaning |
|---|
| 429 | RATE_LIMIT_EXCEEDED | See Retry-After and X-RateLimit-* headers (Rate Limits) |
| 500 | (no code) | Internal error - retry with exponential backoff |
