API Common Errors Reference

This document lists all common errors returned by the API, organized by HTTP status code.

HTTP Status Codes and Common Errors

400 - Bad Request

Errors indicating that the request was malformed or invalid.

Error Code	Error Message	Description	Suggested Action
400	Error when parsing request: <details>	The request body format is invalid or contains syntax errors	Check the request body format and ensure all required fields are present and correctly formatted
400	Invalid environment ID: <details>	The template ID format is invalid	Verify the template ID format matches the expected pattern (e.g., UUID or alias)
400	Invalid template ID format: <details>	The template ID cannot be parsed	Ensure the template ID is correctly formatted
400	Invalid team ID format: <details>	The team ID format is invalid	Verify the team ID is a valid UUID format
400	Invalid request body: <details>	The request body failed validation	Check the request body against the API schema and ensure all required fields are provided
400	Invalid code length	The verification code must be exactly 6 characters	Enter a 6-digit verification code
400	Invalid code, not match	The verification code doesn’t match the code sent to your email	Request a new verification code and try again
400	Invalid code, please contact admin	The verification code is invalid for admin authentication	Contact the administrator for assistance
400	invalid email: <details>	The email address format is invalid	Ensure the email address follows the standard format (e.g., user@example.com)
400	name field is required	The team name field is missing	Provide a team name in the request
400	UserID and TeamID are required	Both user ID and team ID must be provided	Include both user ID and team ID in the request
400	password and token are both required	Both password and reset token are required for password reset	Ensure both password and token are included in the password reset request
400	email and redirectTo are both required	Both email and redirect URL are required	Include both email and redirectTo parameters in the request
400	phone verification code not supported now	Phone verification is currently not supported	Use email verification instead
400	Timeout cannot be greater than <hours> hours	The sandbox timeout exceeds your team’s maximum allowed duration	Reduce the timeout value to be within your team tier limit
400	you need to re-build template to allow secure flag	The template needs to be rebuilt to support the secure flag	Rebuild the template with the secure flag enabled
400	current template build does not support access flag, you need to re-build template to allow it	The template’s envd version is too old (< 0.2.0) to support the access flag	Rebuild the template with envd version 0.2.0 or later
400	validation error: <details>	The request failed OpenAPI schema validation	Check the request parameters against the API documentation
400	Endpoints are deprecated, please update your SDK to use the new endpoints.	You are using deprecated endpoints (/instances or /envs)	Update your SDK to use the new endpoints (e.g., /sandboxes)
400	Endpoint deprecated please update your CLI to the latest version	You are using a deprecated CLI version with multipart/form-data	Update your CLI to the latest version
400	user data information not found, err: <details>	User data could not be found during password reset	Verify the reset token is valid and has not expired
400	failed to generate password, err: <details>	Password generation failed due to an internal error	Try again later or contact support if the issue persists
400	your new password is the same as old password	The new password must be different from the current password	Choose a different password
400	token is expired, please try to reset again	The password reset token has expired	Request a new password reset token
400	Error when parsing API key ID: <details>	The API key ID format is invalid	Ensure the API key ID is a valid UUID format
400	Error when parsing access token ID: <details>	The access token ID format is invalid	Ensure the access token ID is a valid UUID format
400	Bad user id	The user ID format is invalid	Provide a valid user ID (UUID format)
400	Invalid team ID	The team ID validation failed	Verify the team ID is correct and properly formatted
400	email is required	The email field is missing from the request	Include an email address in the request
400	password is required	The password field is missing from the request	Include a password in the request
400	email and password are required	Both email and password fields are missing	Include both email and password in the request
400	invalid user ID format: <details>	The user ID format is invalid or cannot be parsed	Ensure the user ID is a valid UUID format
400	invalid isDefault value: <details>	The isDefault parameter value is invalid	Ensure isDefault is a valid boolean value
400	failed to parse team id, err: <details>	The team ID cannot be parsed	Ensure the team ID is a valid UUID format
400	can not remove a default team member	Attempting to remove a team member who has a default team	Remove the default team assignment first or remove a different team member
400	can not remove the last team member	Attempting to remove the only remaining member of a team	Teams must have at least one member
400	failed to count team members: <details>	Failed to count team members during validation	Retry the request. If the issue persists, contact support
400	sandbox "<sandboxID>" auth info get failed, err: <details>	Failed to retrieve authentication information for the sandbox	Verify the sandbox ID is correct and retry the request
400	failed to exchange Google token: <details>	Failed to exchange Google OAuth authorization code for access token	Verify the authorization code is valid and not expired
400	failed to get Google user info: <details>	Failed to retrieve user information from Google OAuth	Retry the OAuth flow. If the issue persists, contact support
400	failed to exchange GitHub token: <details>	Failed to exchange GitHub OAuth authorization code for access token	Verify the authorization code is valid and not expired
400	failed to get GitHub user info: <details>	Failed to retrieve user information from GitHub OAuth	Retry the OAuth flow. If the issue persists, contact support

401 - Unauthorized

Errors indicating authentication is required or has failed.

Error Code	Error Message	Description	Suggested Action
401	Authentication error	Authentication credentials are missing or invalid	Provide valid authentication credentials (API key, access token, or authorization header)
401	security requirements failed: <details>	The authentication header is missing or invalid	Include a valid authentication header (X-API-Key, Authorization, or X-Supabase-Token)
401	Cannot get the team for the given API key	The API key is invalid or does not exist	Verify the API key is correct or generate a new API key
401	Cannot get the user for the given access token	The access token is invalid or expired	Refresh the access token or request a new one
401	Invalid Access token	The access token format is invalid	Ensure the access token is correctly formatted
401	Backend authentication failed	Backend authentication service failed	Try again later or contact support
401	failed to mask access token: <details>	Failed to mask the access token for display	Retry the request. If the issue persists, contact support

403 - Forbidden

Errors indicating the request is forbidden due to insufficient permissions.

Error Code	Error Message	Description	Suggested Action
403	team forbidden: <details>	Your team does not have permission to access this resource	Contact your team administrator to request access
403	Team '<teamID>' does not have access to the template '<templateID>'	Your team does not have permission to access this template	Request access from the template owner or use a public template
403	Creating team is disabled	Team creation is currently disabled	Contact support if you need to create a team
403	Permission denied, please contact the team administrator	You don’t have sufficient permissions for this operation	Contact your team administrator to grant the necessary permissions

404 - Not Found

Errors indicating the requested resource was not found.

Error Code	Error Message	Description	Suggested Action
404	template '<templateID>' not found	The specified template does not exist	Verify the template ID is correct or check if the template has been deleted
404	Sandbox '<sandboxID>' not found	The specified sandbox does not exist	Verify the sandbox ID is correct or check if the sandbox has been deleted
404	id not found	The API key or access token ID does not exist	Verify the ID is correct or check if it has been deleted
404	email has not been registered, please sign up	The email address is not registered in the system	Sign up with this email address first
404	code not found or expired, please request a new one	The verification code does not exist or has expired	Request a new verification code
404	failed to query operator user info or team, err: <details>	The user or team information could not be found	Verify the user ID or team ID is correct
404	failed to query given email, err: <details>	The email address is not found in the database	Verify the email address is correct or register a new account
404	team not found: <details>	The specified team does not exist	Verify the team ID is correct or check if the team has been deleted
404	tier not found: <details>	The team tier information could not be found	Verify the team ID is correct and the team has an assigned tier
404	default team not found	The user does not have a default team assigned	Assign a default team or verify the user’s team memberships
404	failed to query default team: <details>	Failed to retrieve the user’s default team	Retry the request. If the issue persists, contact support
404	failed to query user teams: <details>	Failed to retrieve user team associations	Retry the request. If the issue persists, contact support
404	failed to query teams: <details>	Failed to retrieve team information	Retry the request. If the issue persists, contact support
404	user team relation not found: <details>	The user-team relationship does not exist	Verify the user ID and team ID are correct
404	user not found: <details>	The specified user does not exist	Verify the user ID is correct or check if the user has been deleted
404	failed to query users: <details>	Failed to retrieve user information	Retry the request. If the issue persists, contact support
404	access token not found: <details>	The specified access token does not exist	Verify the access token ID is correct or check if it has been deleted

409 - Conflict

Errors indicating a conflict with the current state of the resource.

Error Code	Error Message	Description	Suggested Action
409	team named <name> already exists	A team with this name already exists	Choose a different team name
409	email already registered, please sign in	This email address is already registered	Sign in with your existing account or use a different email address
409	email already exists	This email address is already registered	Use a different email address or sign in with your existing account
409	Sandbox <sandboxID> is already being started	A sandbox creation is already in progress for this sandbox ID	Wait for the current creation to complete or use a different sandbox ID

429 - Too Many Requests

Errors indicating rate limiting has been exceeded.

Error Code	Error Message	Description	Suggested Action
429	you have reached the maximum number of concurrent AgentBox sandboxes (<count>). If you need more, please contact us at 'https://agentbox.cloud/contact'	Your team has reached the maximum number of concurrent sandboxes allowed by your tier	Stop some running sandboxes or contact us at https://agentbox.cloud/contact to upgrade your tier
429	too high frequency, please try again in <seconds> seconds	Too many verification code requests in a short period	Wait for the specified number of seconds before requesting another verification code

500 - Internal Server Error

Errors indicating an internal server error occurred. These are typically temporary issues that should be resolved by retrying the request.

Error Code	Error Message	Description	Suggested Action
500	Error when starting transaction	Database transaction initialization failed	Retry the request. If the issue persists, contact support
500	Error when creating API key	API key creation failed due to an internal error	Retry the request. If the issue persists, contact support
500	Server error	An unexpected server error occurred	Retry the request. If the issue persists, contact support
500	failed to check team, err: <details>	Team verification query failed	Retry the request. If the issue persists, contact support
500	failed to get user email, err: <details>	User email lookup failed	Retry the request. If the issue persists, contact support
500	failed to generate token	Token generation service failed	Retry the request. If the issue persists, contact support
500	failed to query base user by email, err: <details>	User database query failed	Retry the request. If the issue persists, contact support
500	failed to create user, err: <details>	User account creation failed	Retry the request. If the issue persists, contact support
500	failed to create auth user, err: <details>	Authentication user creation failed	Retry the request. If the issue persists, contact support
500	failed to save code: <details>	Verification code storage failed	Retry requesting a verification code
500	failed to save time: <details>	Timestamp storage failed	Retry the request
500	failed to send email: <details>	Email delivery service failed	Retry requesting a verification email
500	Failed to send verification email	Email service is temporarily unavailable	Retry requesting a verification email after a few minutes
500	failed to generate recover token, err: <details>	Password recovery token generation failed	Retry the password recovery request
500	failed to reset password, err: <details>	Password reset operation failed	Retry the password reset request
500	internal error: <details>	An internal processing error occurred	Retry the request. If the issue persists, contact support
500	error while getting template: <details>	Template retrieval from database failed	Retry the request. If the issue persists, contact support
500	Error when updating team API key name: <details>	API key name update failed	Retry the request. If the issue persists, contact support
500	Error when deleting API key: <details>	API key deletion failed	Retry the request. If the issue persists, contact support
500	Error when creating team API key: <details>	Team API key creation failed	Retry the request. If the issue persists, contact support
500	Error when getting user: <details>	User retrieval failed	Retry the request. If the issue persists, contact support
500	Error when creating response key mask: <details>	API key masking failed	Retry the request. If the issue persists, contact support
500	Error when generating access token: <details>	Access token generation failed	Retry the request. If the issue persists, contact support
500	Error when creating access token: <details>	Access token creation failed	Retry the request. If the issue persists, contact support
500	Error when masking access token: <details>	Access token masking failed	Retry the request. If the issue persists, contact support
500	Error when deleting access token: <details>	Access token deletion failed	Retry the request. If the issue persists, contact support
500	Error when clearing access token: <details>	Access token clearing failed	Retry the request. If the issue persists, contact support
500	Error when getting team API keys	Team API keys retrieval failed	Retry the request. If the issue persists, contact support
500	Failed to create sandbox: <details>	Sandbox creation failed due to an internal error	Retry creating the sandbox. If the issue persists, contact support
500	Failed to get node to place sandbox on.	No available compute node to host the sandbox	Retry creating the sandbox after a few minutes
500	Failed to get build information for the template	Template build information retrieval failed	Retry the request. If the issue persists, contact support
500	Failed to create sandbox	Sandbox creation failed (generic error)	Retry creating the sandbox. If the issue persists, contact support
500	Not support env type: <type>, only support for [ linux_arm64 | linux_x86 | android ]	The specified environment type is not supported	Use one of the supported environment types: linux_arm64, linux_x86, or android
500	error during sandbox access token generation	Envd access token generation failed	Retry the request. If the issue persists, contact support
500	Error when setting sandbox timeout	Sandbox timeout update failed	Retry the request. If the issue persists, contact support
500	Failed to get inbox messages: <details>	Notification inbox retrieval failed	Retry the request. If the issue persists, contact support
500	Failed to get filtered inbox messages: <details>	Filtered inbox messages retrieval failed	Retry the request. If the issue persists, contact support
500	Failed to send alert: <details>	Alert notification delivery failed	Retry the request. If the issue persists, contact support
500	Error executing query: <details>	Failed to execute Prometheus query	Retry the request. If the issue persists, contact support
500	failed to create base user: <details>	Base user account creation failed during OAuth sign-in	Retry the OAuth sign-in. If the issue persists, contact support
500	failed to create auth user, err: <details>	Authentication user creation failed during OAuth sign-in	Retry the OAuth sign-in. If the issue persists, contact support
500	failed to issue refresh token: <details>	Failed to generate refresh token after OAuth authentication	Retry the OAuth sign-in. If the issue persists, contact support
500	failed to query user by email: <details>	User database query failed during OAuth sign-in	Retry the OAuth sign-in. If the issue persists, contact support
500	failed to update user: <details>	User profile update failed	Retry the request. If the issue persists, contact support
500	error generating sandbox access token: <details>	Failed to generate access token for secure sandbox access	Retry the request. If the issue persists, contact support
500	failed to delete member, err: <details>	Failed to remove team member	Retry the request. If the issue persists, contact support
500	Error when creating user team relation: <details>	Failed to create user-team relationship	Retry the request. If the issue persists, contact support

503 - Service Unavailable

Errors indicating the service is temporarily unavailable.

Error Code	Error Message	Description	Suggested Action
503	Service is unavailable	The service is temporarily unavailable, typically because compute nodes are not ready	Wait a few minutes and retry the request
503	Metrics handler is not configured	The Prometheus metrics handler is not configured or initialized	Contact support to enable metrics functionality

---

Error Categories by Feature

Authentication & Authorization

Common errors related to authentication and authorization:

• 400: OAuth authentication failures
  • Common errors: failed to exchange Google token, failed to get Google user info, failed to exchange GitHub token, failed to get GitHub user info
  • Retry the OAuth flow. If the issue persists, contact support
• 401: Missing or invalid API key, access token, or authorization header
  • Check that authentication credentials are correctly included in the request headers
  • Verify API keys and tokens are valid and not expired
  • Common errors: failed to mask access token, Authentication failed. Please check your email and password.
• 403: Team access denied, insufficient permissions
  • Contact your team administrator to request access to the resource
  • Verify your team has the necessary permissions for the operation

User Management

Common errors related to user account operations:

• 400: Invalid email format, missing required fields
  • Ensure email addresses follow the standard format
  • Verify all required fields are provided in the request
  • Common missing fields: email, password, or both email and password
• 404: User not found, email not registered
  • Verify the email address is correct
  • Sign up with the email address if it’s not registered
  • Common errors: user not found, failed to query users, failed to query user by email
• 409: Email already registered
  • Sign in with your existing account or use a different email address
• 500: User creation/update failures
  • Retry the operation. If the issue persists, contact support
  • Common errors: failed to create base user, failed to create auth user, failed to update user, failed to issue refresh token

Team Management

Common errors related to team operations:

• 400: Invalid team name, missing required fields
  • Ensure the team name meets the requirements
  • Verify all required fields are provided
• 403: Team creation disabled, insufficient permissions
  • Contact support if team creation is needed
  • Request permissions from your team administrator
• 404: Team not found
  • Verify the team ID is correct
  • Common errors: team not found, failed to query teams, failed to query user teams, user team relation not found, default team not found
• 409: Team name already exists
  • Choose a different team name
• 500: Team operation failures
  • Retry the operation. If the issue persists, contact support
  • Common errors: Error when creating user team relation, failed to delete member, failed to count team members
• 400: Team member removal restrictions
  • Cannot remove a default team member or the last team member
  • Common errors: can not remove a default team member, can not remove the last team member

Template Management

Common errors related to template operations:

• 400: Invalid template ID format
  • Verify the template ID is correctly formatted (UUID or alias)
• 403: Team doesn’t have access to template
  • Request access from the template owner or use a public template
• 404: Template not found
  • Verify the template ID is correct or check if the template has been deleted
• 500: Template retrieval/build failures
  • Retry the operation. If the issue persists, contact support

Sandbox Management

Common errors related to sandbox operations:

• 400: Invalid sandbox configuration, timeout exceeds limit
  • Verify sandbox configuration parameters
  • Ensure timeout is within your team tier limit
• 404: Sandbox not found
  • Verify the sandbox ID is correct or check if the sandbox has been deleted
• 409: Sandbox already being started
  • Wait for the current creation to complete or use a different sandbox ID
• 429: Maximum concurrent sandboxes reached
  • Stop some running sandboxes or upgrade your tier
• 500: Sandbox creation failures, node unavailable
  • Retry creating the sandbox after a few minutes
  • If the issue persists, contact support
• 503: Service unavailable (nodes not ready)
  • Wait a few minutes and retry the request

Verification Codes

Common errors related to verification code operations:

• 400: Invalid code format, code mismatch
  • Ensure the verification code is exactly 6 characters
  • Request a new code if the current one doesn’t match
• 404: Code not found or expired
  • Request a new verification code
• 429: Too many verification requests
  • Wait for the specified cooldown period before requesting another code
  • Common errors: too high frequency, please try again in <seconds> seconds
• 500: Code generation/saving failures
  • Retry requesting a verification code

API Keys & Access Tokens

Common errors related to API keys and access tokens:

• 400: Invalid ID format
  • Ensure IDs are in valid UUID format
  • Common errors: invalid user ID format, invalid team ID format, failed to parse team id
• 404: Key/token not found
  • Verify the ID is correct or check if it has been deleted
  • Common errors: access token not found, id not found
• 401: Access token masking failures
  • Failed to mask access token for secure display
  • Common errors: failed to mask access token
• 500: Key/token operation failures
  • Retry the operation. If the issue persists, contact support
  • Common errors: error generating sandbox access token, Error when masking access token

---