Announcing the Appwrite OSS Fund, Learn More! 🤑
Docs

Error Codes

Appwrite uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, invalid input, etc.). Codes in the 5xx range indicate an error with the Appwrite server, but these are rare.

Code Text Description
200 OK Success!
201 Created The requested resource has been created successfully.
204 No Content The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. This status will usually return on successful delete operations.
301 Moved Permanently The URL of the requested resource has been changed permanently. The new URL is given in the response.
304 Not Modified There was no new data to return.
400 Bad Request The request was invalid or cannot be otherwise served. An accompanying error message will explain further. Requests with wrong or invalid input will yield this response.
401 Unauthorized Missing or incorrect authentication credentials can happen when the API key or user permission is not sufficient.
403 Forbidden The request is understood, but it has been refused, or access is not allowed. An accompanying error message will explain why. Make sure to register your app in your project's dashboard platform list.
404 Not Found The URI requested is invalid or the resource requested, such as a user, does not exist.
409 Conflict This response is sent when a request conflicts with the current state of the server. This status code will usually appear when you're trying to create an already existing resource.
416 Invalid Range Invalid value in the range or content-range headers. Usually returned while uploading or downloading files using range header but the provided range value is not valid.
429 Too Many Requests Returned in when a request cannot be served due to the application’s rate limit having been exhausted for the resource. See Rate Limits
500 Internal Server Error Something is broken. Contact our team, or raise a GitHub issue.
501 Not Implemented The feature is not implemented. Usually returned when the project owner has disabled an auth method or an entire service.
503 Service Unavailable The Appwrite servers are up but overloaded with requests. Try again later.
504 Gateway timeout The Appwrite servers are up, but the request couldn’t be serviced due to some failure within the stack. Try again later.

Error Messages

When the Appwrite APIs return error messages, it does so in JSON format. For example, an error might look like this:

{
    "message": "Invalid id: Parameter must be a valid number",
    "type": "argument_invalid",
    "code": 400
}

Error Types

Appwrite also passes convenient error types in addition to the HTTP response codes to help you get more fine grained control over what went wrong and allowing you to display relevant error messages in your applications. Error types are are convenient to identify the type of error that occurred.

For eg: A 400 HTTP response code could indicate a Bad Request due to a variety of reasons and error types can help you pinpoint the exact 400 error. Appwrite currently supports the following error types:

Code Type Description
400 general_mock General errors thrown by the mock controller used for testing.
400 general_argument_invalid The request contains one or more invalid arguments. Please refer to the endpoint documentation.
400 general_query_limit_exceeded Query limit exceeded for the current attribute. Usage of more than 100 query values on a single attribute is prohibited.
400 general_query_invalid The query's syntax is invalid. Please check the query and try again.
400 general_cursor_not_found The cursor is invalid. This can happen if the item represented by the cursor has been deleted.
400 user_password_mismatch Passwords do not match. Please check the password and confirm password.
400 storage_device_not_found The requested storage device could not be found.
400 storage_file_empty Empty file passed to the endpoint.
400 storage_file_type_unsupported The file type is not supported.
400 storage_invalid_file_size The file size is either not valid or exceeds the maximum allowed size. Please check the file or the value of the _APP_STORAGE_LIMIT environment variable.
400 storage_invalid_content_range The content range is invalid. Please check the value of the Content-Range header.
400 build_not_ready Build with the requested ID is builing and not ready for execution.
400 build_in_progress Build with the requested ID is already in progress. Please wait before you can retry.
400 collection_limit_exceeded The maximum number of collections has been reached.
400 document_invalid_structure The document structure is invalid. Please ensure the attributes match the collection definition.
400 document_missing_payload The document payload is missing.
400 attribute_unknown The attribute required for the index could not be found. Please confirm all your attributes are in the available state.
400 attribute_not_available The requested attribute is not yet available. Please try again later.
400 attribute_format_unsupported The requested attribute format is not supported.
400 attribute_default_unsupported Default values cannot be set for array and required attributes.
400 attribute_limit_exceeded The maximum number of attributes has been reached.
400 attribute_value_invalid The attribute value is invalid. Please check the type, range and value of the attribute.
400 index_limit_exceeded The maximum number of indexes has been reached.
400 project_unknown The project ID is either missing or not valid. Please check the value of the X-Appwrite-Project header to ensure the correct project ID is being used.
400 project_invalid_success_url Invalid URL received for OAuth success redirect.
400 project_invalid_failure_url Invalid URL received for OAuth failure redirect.
400 project_missing_user_id Failed to obtain user ID from the OAuth provider.
401 general_access_forbidden Access to this API is forbidden.
401 general_unauthorized_scope The current user or API key does not have the required scopes to access the requested resource.
401 user_jwt_invalid The JWT token is invalid. Please check the value of the X-Appwrite-JWT header to ensure the correct token is being used.
401 user_blocked The current user has been blocked. You can unblock the user from the Appwrite console.
401 user_invalid_token Invalid token passed in the request.
401 user_email_not_whitelisted The user's email is not part of the whitelist. Please check the _APP_CONSOLE_WHITELIST_EMAILS environment variable of your Appwrite server.
401 user_ip_not_whitelisted The user's IP address is not part of the whitelist. Please check the _APP_CONSOLE_WHITELIST_IPS environment variable of your Appwrite server.
401 user_invalid_credentials Invalid credentials. Please check the email and password.
401 user_anonymous_console_prohibited Anonymous users cannot be created for the console project.
401 user_session_already_exists Creation of anonymous users is prohibited when a session is active.
401 user_unauthorized The current user is not authorized to perform the requested action.
401 team_invalid_secret The team invitation secret is invalid.
401 team_invite_mismatch The invite does not belong to the current user.
401 domain_verification_failed Domain verification for the requested domain has failed.
403 general_unknown_origin The request originated from an unknown origin. If you trust this domain, please list it as a trusted platform in the Appwrite console.
403 storage_invalid_file The uploaded file is invalid. Please check the file and try again.
404 general_route_not_found The requested route was not found. Please refer to the docs and try again.
404 user_not_found User with the requested ID could not be found.
404 user_session_not_found The current user session could not be found.
404 team_not_found Team with the requested ID could not be found.
404 team_invite_not_found The requested team invitation could not be found.
404 team_membership_mismatch The membership ID does not belong to the team ID.
404 membership_not_found Membership with the requested ID could not be found.
404 avatar_set_not_found The requested avatar set could not be found.
404 avatar_not_found The request avatar could not be found.
404 avatar_image_not_found The requested image was not found at the URL.
404 avatar_remote_url_failed Failed to fetch favicon from the requested URL.
404 avatar_icon_not_found The requested favicon could not be found.
404 storage_file_not_found The requested file could not be found.
404 storage_bucket_not_found Storage bucket with the requested ID could not be found.
404 function_not_found Function with the requested ID could not be found.
404 function_runtime_unsupported The requested runtime is either inactive or unsupported. Please check the value of the _APP_FUNCTIONS_RUNTIMES environment variable.
404 build_not_found Build with the requested ID could not be found.
404 deployment_not_found Deployment with the requested ID could not be found.
404 execution_not_found Execution with the requested ID could not be found.
404 collection_not_found Collection with the requested ID could not be found.
404 document_not_found Document with the requested ID could not be found.
404 attribute_not_found Attribute with the requested ID could not be found.
404 index_not_found Index with the requested ID could not be found.
404 project_not_found Project with the requested ID could not be found. Please check the value of the X-Appwrite-Project header to ensure the correct project ID is being used.
404 webhook_not_found Webhook with the requested ID could not be found.
404 key_not_found Key with the requested ID could not be found.
404 platform_not_found Platform with the requested ID could not be found.
404 domain_not_found Domain with the requested ID could not be found.
409 user_already_exists A user with the same email ID already exists in your project.
409 user_email_already_exists Another user with the same email already exists in the current project.
409 team_invite_already_exists The current user has already received an invitation to join the team.
409 storage_bucket_already_exists A storage bucket with the requested ID already exists.
409 collection_already_exists A collection with the requested ID already exists.
409 document_already_exists Document with the requested ID already exists.
409 attribute_already_exists Attribute with the requested ID already exists.
409 index_already_exists Index with the requested ID already exists.
409 domain_already_exists A Domain with the requested ID already exists.
412 user_password_reset_required The current user requires a password reset.
412 project_provider_disabled The chosen OAuth provider is disabled. You can enable the OAuth provider using the Appwrite console.
416 storage_invalid_range The requested range is not satisfiable. Please check the value of the Range header.
429 general_rate_limit_exceeded Rate limit for the current endpoint has been exceeded. Please try again after some time.
500 general_unknown An unknown error has occured. Please check the logs for more information.
500 general_server_error An internal server error occurred.
500 general_protocol_unsupported The request cannot be fulfilled with the current protocol. Please check the value of the _APP_OPTIONS_FORCE_HTTPS environment variable.
501 user_count_exceeded The current project has exceeded the maximum number of users. Please check your user limit in the Appwrite console.
501 user_auth_method_unsupported The requested authentication method is either disabled or unsupported. Please check the supported authentication methods in the Appwrite console.
501 project_provider_unsupported The chosen OAuth provider is unsupported. Please check the docs for the complete list of supported OAuth providers.
503 general_service_disabled The requested service is disabled. You can enable the service from the Appwrite console.
503 general_smtp_disabled SMTP is disabled on your Appwrite instance. You can learn more about setting up SMTP in our docs.