Response 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. |
202 | Accepted | The requested change has been accepted for processing but has not been completed. |
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. |
413 | Payload Too Large | This indicates that the request entity is larger than limits defined by server. This status code will usually appear happen when uploading a file or function that is too large |
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 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 | user_phone_not_found | The current user does not have a phone number associated with their account. |
400 | user_missing_id | Missing ID from OAuth2 provider. |
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 given file extension 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 building 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 redirect URL for OAuth success. |
400 | project_invalid_failure_url | Invalid redirect URL for OAuth failure. |
400 | project_reserved_project | The project ID is reserved. Please choose another project ID. |
400 | graphql_no_query | Param "query" is not optional. |
400 | graphql_too_many_queries | Too many queries. |
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 | Console registration is restricted to specific emails. Contact your administrator for more information. |
401 | user_ip_not_whitelisted | Console registration is restricted to specific IPs. Contact your administrator for more information. |
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 | project_key_expired | The project key has expired. Please generate a new key using the Appwrite console. |
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 API 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 | database_not_found | Database not 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. |
404 | variable_not_found | Variable with the requested ID could not be found. |
409 | user_already_exists | A user with the same email already exists in your project. |
409 | user_email_already_exists | A user with the same email already exists in the current project. |
409 | user_phone_already_exists | A user with the same phone number already exists in the current project. |
409 | team_invite_already_exists | User has already been invited or is already a member of this team |
409 | membership_already_confirmed | Membership already confirmed |
409 | storage_bucket_already_exists | A storage bucket with the requested ID already exists. |
409 | database_already_exists | Database 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. |
409 | variable_already_exists | Variable with the same ID already exists in your project. |
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 Create OAuth2 Session 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. |
503 | general_phone_disabled | Phone provider is not configured. Please check the _APP_SMS_PROVIDER environment variable of your Appwrite server. |