⚠️ ERROR REFERENCE

API Error Catalogue

Every /beak/* error code with HTTP status, cause, operator fix, and user-facing message. Search by code, endpoint, or keyword.

No errors match your search. Try a different keyword or clear the filter.
400 — Bad Request
Cause
One or more required fields are absent from the JSON request body (e.g., email, password, display_name, code).
Operator Fix
Validate that all required fields are present and non-empty before sending the request. Review the endpoint schema in the OpenAPI spec.
User-Facing Message
"Something went wrong — please check your details and try again."
Example Response
{"error": "Missing required field: email"}
Cause
The email field does not conform to RFC 5321 format. Common causes: missing @, invalid TLD, or whitespace in the value.
Operator Fix
Run client-side email validation (e.g., HTML5 type="email" or regex) before submitting. Strip whitespace from inputs.
User-Facing Message
"Please enter a valid email address."
Example Response
{"error": "Invalid email format"}
Cause
The 6-digit OTP submitted does not match the code stored in Cognito for the given email. Originates from AWS Cognito CodeMismatchException. Codes are case-sensitive strings.
Operator Fix
Ensure the code field is sent as a string (not integer). Do not alter or trim the value. If repeated failures occur, prompt the user to request a new code via re-hatch or re-peck.
User-Facing Message
"That code doesn't look right. Please check and try again, or request a new one."
Example Response
{"error": "CodeMismatchException", "message": "Invalid verification code"}
Cause
The OTP has passed its validity window (15 minutes). Originates from AWS Cognito ExpiredCodeException. Once expired, the code cannot be used even if correct.
Operator Fix
Surface a "Resend code" option in the UI. Time the OTP input form to show a countdown. Inform users that the code expires after 15 minutes.
User-Facing Message
"That code has expired. We've sent a new one to your email — please check and try again."
Example Response
{"error": "ExpiredCodeException", "message": "Verification code has expired"}
Cause
The supplied password does not meet Cognito's password policy: minimum 8 characters, at least one uppercase, one lowercase, one digit, and one special character.
Operator Fix
Enforce the password policy client-side with a strength indicator. Display the requirements clearly before submission. Regex: /^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)(?=.*\W).{8,}/.
User-Facing Message
"Password must be at least 8 characters and include uppercase, lowercase, a number, and a special character."
Example Response
{"error": "InvalidPasswordException", "message": "Password does not meet requirements"}
401 — Unauthorized
Cause
The Authorization: Bearer {token} header is absent or malformed. All authenticated endpoints require a valid session token.
Operator Fix
Retrieve a token via POST /beak/auth before calling authenticated endpoints. Store it securely and include it in all subsequent requests. Check for header typos.
User-Facing Message
"You need to be signed in to do that. Please sign in and try again."
Example Response
{"error": "Authorization required"}
Cause
The JWT token is invalid (tampered), has expired (Cognito tokens expire after 1 hour), or belongs to a rotated Beak Key. Originates from Cognito NotAuthorizedException.
Operator Fix
Implement token refresh logic: catch 401 responses, re-authenticate via POST /beak/auth, then retry the original request. Store token_expiry alongside the token to proactively refresh before expiry.
User-Facing Message
"Your session has expired. Please sign in again."
Example Response
{"error": "NotAuthorizedException", "message": "Token is invalid or has expired"}
Cause
The email/password combination submitted to /beak/auth does not match a valid Cognito user. Also returned when the email is not yet verified.
Operator Fix
Do not disclose whether it was the email or password that was wrong (security best practice). After 5 consecutive failures, surface a "Forgot password?" recovery path. Cognito may temporarily lock the account after repeated failures.
User-Facing Message
"Incorrect email or password. Please try again."
Example Response
{"error": "NotAuthorizedException", "message": "Incorrect username or password"}
403 — Forbidden
Cause
The Cloudflare Turnstile challenge token was missing, invalid, or expired. Turnstile is used to prevent automated abuse on hatch, auth, and peck endpoints. Each token is single-use and expires within 5 minutes.
Operator Fix
Ensure the Turnstile widget is rendered and the token is submitted with each request. Tokens are invalidated after a single use — generate a fresh token for each form submission. For server-to-server integrations, contact the platform for an exemption path.
User-Facing Message
"Security check failed. Please try again — make sure your browser has JavaScript enabled."
Example Response
{"error": "Turnstile verification failed"}
Cause
The requesting duckling's current trust tier (T0 or T1) does not meet the minimum tier required by the target endpoint or the target duckling's accept policy. For example, bond requests require T1+.
Operator Fix
Verify the duckling's tier via GET /beak/metrics or GET /beak/spaceducks before attempting the action. Display a tier upgrade prompt if tier is T0. Direct users to complete email verification to reach T1.
User-Facing Message
"This action requires a higher trust level. Verify your email to unlock this feature."
Example Response
{"error": "Forbidden", "message": "Insufficient trust tier. T1 required."}
404 — Not Found
Cause
The email address provided does not correspond to any registered duckling in the system. The account may never have been created, or the email may be misspelled.
Operator Fix
Do not disclose whether an email is registered (prevents account enumeration). Surface a generic error message and offer both login and hatch paths. Log the lookup for abuse monitoring.
User-Facing Message
"No account found. Check your email or create a new Space Duck identity."
Example Response
{"error": "Duckling not found"}
Cause
The peck_id submitted does not match any active peck record. The peck may have already been approved, rejected, or expired.
Operator Fix
Store peck_id immediately on creation and validate it before calling approve. Pecks expire after 24 hours if not acted upon. Display the peck status before surfacing an approve form.
User-Facing Message
"This connection request has expired or was already handled."
Example Response
{"error": "Peck not found or already resolved"}
Cause
The requested path does not match any known Lambda route. Common causes: typo in the URL path, trailing slash, or calling an endpoint that does not yet exist in the current Lambda version.
Operator Fix
Verify the endpoint path against the OpenAPI spec. Check that the prod stage is included in the URL base. Avoid trailing slashes unless documented.
User-Facing Message
"Something went wrong. Please try again or contact support."
Example Response
{"message": "Missing Authentication Token"} (AWS API Gateway default)
409 — Conflict
Cause
A Cognito user with the given email already exists. Originates from Cognito UsernameExistsException. This is the most common error from the hatch endpoint.
Operator Fix
Redirect the user to the sign-in flow (/auth.html) with a helpful message. Do not expose whether the email was found (prevents enumeration in sensitive contexts). Consider a "Forgot password?" link.
User-Facing Message
"An account with this email already exists. Sign in instead, or reset your password."
Example Response
{"error": "UsernameExistsException", "message": "An account with this email already exists"}
Cause
An unresolved peck already exists between the same sender and target with the same peck type. Duplicate pecks are rejected until the first is approved, rejected, or expired.
Operator Fix
Track pending peck IDs in your application state. Before sending a new peck, check whether one is already outstanding. Display the existing peck status to the user.
User-Facing Message
"A connection request to this duck is already pending. Wait for a response before sending another."
Example Response
{"error": "Conflict", "message": "A pending peck already exists for this pair"}
429 — Rate Limited
Cause
The request rate has exceeded the per-IP or per-duckling limit for the endpoint. Enforced by API Gateway and Lambda-level checks. Default limits: 10 req/min for auth/hatch (unauthenticated), 60 req/min for authenticated endpoints, 1 pulse/min.
Operator Fix
Implement exponential backoff with jitter. Respect the Retry-After header when present. Cache read-only responses locally. For burst requirements, contact the platform for a higher-tier API allocation. Trust tier T2+ unlocks higher rate limits.
User-Facing Message
"You're going too fast. Please wait a moment and try again."
Example Response
{"error": "Too Many Requests", "retry_after_seconds": 30}
500 — Server Error
Cause
An unhandled exception occurred in the Lambda function. Common causes: DynamoDB timeout or throttling, Cognito API unavailability, unexpected payload format causing a Python exception, or AWS SES quota exhaustion (for OTP delivery).
Operator Fix
Retry with exponential backoff — 500 errors are often transient. If the issue persists (>5 min), check Platform Status. Report persistent failures via GitHub Issues with the request timestamp and endpoint.
User-Facing Message
"Something went wrong on our end. Please try again in a moment."
Example Response
{"error": "Internal server error"}
Cause
AWS Simple Email Service (SES) failed to deliver the OTP email. Causes: SES sandbox restrictions (only verified addresses can receive in sandbox mode), daily send quota exceeded, or bounced destination address.
Operator Fix
In sandbox deployments, pre-verify destination email addresses in the SES console. For production, request SES production access. Monitor the SES bounce/complaint dashboard to prevent suppression of your sending domain.
User-Facing Message
"We couldn't send the verification email. Please check your email address or try again shortly."
Example Response
{"error": "Email delivery failed. Please try again."}
Developer Hub SDK Reference SDK Playground OpenAPI Spec Platform Status