Skip to Content

Every error code the API documents, with the statuses it comes with and the TypeScript SDK methods that can answer it.

Every error code the API's document names, 333 of them, read from each operation's refusals. A failed call's code is one of these (Errors and retries): decide on the code, never on the status alone, since one status covers several.

What a code means for a method, and whether it is worth sending again, is on that method's page, under Errors. Any call can also answer 503 temporary_failure (and, for a call that reaches a mailbox, mailbox_reopening, mailbox_closing or mailbox_unavailable): wait its Retry-After, then send again, which is safe for a read and for a write that carries an idempotency key.

CodeStatusMethods
account_credentials_required40316 methods of credentials, identities, accountAddressLists, mailboxAddressLists
account_deleted403, 4099 methods of accounts, domains, identities, mta
account_id_required400apiKeys.create
account_over_quota507messages.append, messages.compose, messages.send, threads.reply, mta.submitOutbound, mta.deliverInbound
account_purged410accounts.delete, accounts.restore
account_required400, 409domains.create, domains.setEventWebhook, identities.create, identities.list, mailboxes.setEventWebhook, mailboxes.setMessageWebhook
address_blocked403identities.create, routes.create
address_not_routed400identities.update
address_taken409identities.create
alias_chain400domains.create, domains.update
alias_conflict409domains.create, domains.update
alias_cross_account400domains.create, domains.update
alias_fbl_exclusive400, 409domains.create, domains.update
alias_self400domains.create, domains.update
alias_target_unresolvable400patterns.create, patterns.update
already_canceled409scheduled.reschedule
already_scheduled409messages.sendDraft
always_verified400verifiedRecipients.add
ambiguous_sender400messages.sendDraft
analytics_query_failed502accounts.getTraffic, accounts.getRequests, accounts.listEvents, domains.getTraffic, domains.listEvents
analytics_unavailable503accounts.getTraffic, accounts.getRequests, accounts.listEvents, domains.getTraffic, domains.listEvents
attachments_too_large413messages.send, threads.reply
auto_submitted_conflict400messages.send, threads.reply
blob_missing500messages.getContent, messages.getRaw, messages.getPart, messages.getInvitation
blob_unavailable500messages.send, threads.reply
blob_unreadable503messages.sendDraft
body_too_large400templates.setVariant, templates.render
cannot_calculate_changes410labels.listVanished, messages.getChanges
cannot_mint_for_other_account403apiKeys.create
cannot_unsend409scheduled.reschedule, scheduled.cancel
challenge_expired400securityKeys.finishRegistration
components_conflict409calendars.update, addressbooks.update
confirmation_cleared403recovery.confirmAddress, forwarding.confirmDestination
confirmation_limit_reached429verifiedRecipients.add
conflict409pickups.update, pickups.delete, calendars.respondToInvitation, calendarObjects.respond
control_exclusive400identities.update
credential_reissue_required404pim.getFeed
credential_scope403identities.listClients, mailboxes.checkSendAs, messages.send, messages.sendDraft, threads.reply, mta.submitOutbound
default_collection403calendars.delete, addressbooks.delete
delete_target_exclusive400messages.deleteMany
delete_target_required400messages.deleteMany
delivery_id_reused409messages.send, messages.sendDraft, threads.reply, mta.submitOutbound
delivery_id_too_long400threads.reply, templates.send
delivery_meta_invalid_json400mta.submitOutbound, mta.deliverInbound
delivery_meta_not_object400mta.submitOutbound, mta.deliverInbound
delivery_meta_too_large400mta.submitOutbound, mta.deliverInbound
delivery_status_too_large413deliveries.list
destination_chain_too_long40011 methods of routes, patterns, rules, sieve, forwarding
destination_fans_out400forwarding.setForwardAll, forwarding.addDestination
destination_is_self400routes.create, routes.update, patterns.create, patterns.update, rules.set, sieve.putScript, forwarding.setForwardAll, forwarding.addDestination
destination_loops40011 methods of routes, patterns, rules, sieve, forwarding
destination_not_permitted400forwarding.setForwardAll, forwarding.addDestination
destination_requires_type400routes.update, patterns.update
destination_unverified400rules.set, sieve.putScript, forwarding.setForwardAll
disabled409pickups.run
dns_status_not_writable403domains.update
domain_blocked403domains.create
domain_claimed_elsewhere409domains.create
domain_has_hostnames409domains.delete
domain_has_patterns409domains.delete
domain_has_routes409domains.delete
domain_in_use409domains.update
domain_is_alias400, 409hostnames.set, identities.create, identities.update, routes.create, patterns.create
domain_is_alias_target409domains.update, domains.delete
domain_not_verified400domains.create
domain_transition_in_progress409domains.create, domains.update, domains.delete
domain_unavailable409domains.create
duplicate_credential400securityKeys.finishRegistration
duplicate_recipient400templates.send
duplicate_source409pickups.create
empty_body400, 4229 methods, in 8 namespaces
empty_import400calendars.import, addressbooks.import
empty_patch400domains.update, routes.update, patterns.update
empty_query400search.fullText, search.semantic
ephemeral_immutable400identities.update
ephemeral_requires_account400identities.create
expand_requires_range400calendarObjects.list, addressbookObjects.list
filter_required400search.updateMatches
folder_shared409labels.delete, labels.deleteById
forbidden4039 methods of calendars, calendarObjects, addressbooks, addressbookObjects, realtime
forward_rate_limited429mta.deliverInbound
forwarding_mail_unavailable503forwarding.addDestination
from_not_owned403messages.sendDraft, mta.submitOutbound
from_not_sendable400templates.create, templates.update, templates.send
from_sending_disabled403messages.sendDraft, mta.submitOutbound
from_sending_paused429messages.sendDraft, mta.submitOutbound
gesture_required400messages.copy
gone410identities.restore
group_delete_in_flight409routes.create
group_has_persona409routes.update
grouped_search_unpaginated400search.fullText
header_block_too_large400mta.submitOutbound
header_newline400messages.compose, messages.send
hostname_in_foreign_domain400hostnames.set
hostname_not_subdomain400hostnames.set
hostname_reserved400hostnames.set
hostname_taken409hostnames.set
href_taken409calendarObjects.move, calendarObjects.restore, addressbookObjects.move, addressbookObjects.restore
idempotency_key_invalid400identities.create, identities.update
idempotency_key_required400identities.create
idempotency_key_reused409identities.create, identities.update
idempotency_key_unsupported400identities.update
identity_deleted409identities.create
idmax_required400search.updateMatches
import_too_large413calendars.import, addressbooks.import
inbound_edge_cap409routes.create, routes.update, routes.addMember, routes.addMembers, routes.replaceMembers, forwarding.setForwardAll
ingestion_not_writable403domains.create, domains.update
insufficient_scope40310 methods of accounts, mailboxes, filtering, mta, suppressions
internal500messages.send, threads.reply
internal_error500mta.submitOutbound, mta.deliverInbound
invalid_address40011 methods of credentials, identities, mailboxes, routes, patterns, messages
invalid_alias_address400patterns.create, patterns.update
invalid_base64400messages.compose, messages.send
invalid_bounce400mta.submitOutbound
invalid_code403recovery.confirmAddress, forwarding.confirmDestination
invalid_components400calendars.create, calendars.update, addressbooks.create, addressbooks.update
invalid_current_password403passwords.change
invalid_cursor40011 methods, in 9 namespaces
invalid_domain400apiKeys.create, domains.create, domains.update
invalid_envelope400mta.submitOutbound, mta.deliverInbound
invalid_filter400search.query, search.updateMatches, search.snippets
invalid_flag400messages.compose
invalid_from400messages.sendDraft, mta.submitOutbound
invalid_header400messages.append
invalid_hostname400hostnames.set
invalid_href400calendarObjects.put, calendarObjects.move, addressbookObjects.put, addressbookObjects.move
invalid_invitation400calendars.respondToInvitation
invalid_keyword400labels.updateMessages, search.updateMatches
invalid_member_address400routes.addMember, routes.addMembers, routes.replaceMembers
invalid_name400calendars.create, calendars.update, addressbooks.create, addressbooks.update
invalid_origin400securityKeys.finishRegistration
invalid_password403credentials.create, recovery.setAddress, recovery.removeAddress, recovery.createCodes, securityKeys.beginRegistration, securityKeys.remove
invalid_pattern40025 methods of patterns, accountAddressLists, mailboxAddressLists
invalid_recipients400messages.sendDraft
invalid_request400deliveries.list
invalid_save400mta.submitOutbound
invalid_script422rules.set, sieve.putScript
invalid_sync_token410calendars.getChanges, addressbooks.getChanges
invalid_token403deliveries.download
invalid_username400credentials.create
invalid_verification_code400pushSubscriptions.update
invalid_window422vacation.set
invitation_too_large413messages.getInvitation, calendars.respondToInvitation
is_organizer403calendars.respondToInvitation
label_exists409labels.create
label_not_applicable400messages.list
label_purge_exclusive400messages.delete
learning_unavailable503messages.learn, messages.learnMany
length_required411uploads.create, mta.submitOutbound, mta.deliverInbound, templates.create, templates.update, templates.setVariant, templates.render, templates.send
list_full409accountAddressLists.addEntry, accountAddressLists.addEntries, accountAddressLists.importEntries, mailboxAddressLists.addEntry, mailboxAddressLists.addEntries, mailboxAddressLists.importEntries
list_limit_reached409accountAddressLists.create, mailboxAddressLists.create
list_name_taken409accountAddressLists.create, accountAddressLists.update, mailboxAddressLists.create, mailboxAddressLists.update
mailbox_closing503templates.send
mailbox_credential_required403pushSubscriptions.create, pushSubscriptions.list, pushSubscriptions.update, pushSubscriptions.delete
mailbox_gone403, 404, 410messages.compose, messages.send, messages.sendDraft, threads.reply, mta.submitOutbound, mta.deliverInbound, realtime.mailbox, realtime.pim
mailbox_is_group_persona409identities.delete, routes.create, routes.update, rules.set, sieve.putScript, sieve.renameScript, sieve.activate
mailbox_limit_reached403identities.create
mailbox_reopening503templates.send
member_exists409routes.addMember
member_limit400routes.addMember, routes.addMembers, routes.replaceMembers
message_too_complex422messages.getContent, messages.getPart, calendars.respondToInvitation
message_too_large413messages.getContent, messages.getPart, messages.getInvitation, deliveries.download, calendars.respondToInvitation
message_webhook_requires_address400identities.create
metadata_too_large413uploads.create
missing_delivery_id400mta.submitOutbound, mta.deliverInbound
missing_variable400templates.render, templates.send
multiple_uids400calendars.respondToInvitation, calendarObjects.put, addressbookObjects.put
name_exists409sieve.putScript, sieve.renameScript
name_taken409calendars.create, calendars.update, calendars.restore, addressbooks.create, addressbooks.update, addressbooks.restore
no_invitation404messages.getInvitation
no_mail_store400, 409identities.create, identities.update
no_password_credential409credentials.create, passwords.change, recovery.setAddress, recovery.removeAddress, recovery.createCodes, securityKeys.beginRegistration, securityKeys.remove
no_pending_address400recovery.confirmAddress
no_pending_code400forwarding.confirmDestination
no_primary_address400threads.reply
no_recipients400messages.send, messages.sendDraft
no_reply_target400threads.reply
no_username409passwords.reset
no_variant_for_language400templates.render, templates.send
no_webhook400routes.update
not_a_draft409messages.sendDraft
not_attendee403calendars.respondToInvitation, calendarObjects.respond
not_calendar400calendars.import, addressbooks.import
not_deleted409accounts.restore, identities.restore
not_embedded409search.similar
not_found40459 methods, in 13 namespaces
not_holdable400identities.create, identities.update
not_in_label409messages.update
not_labeled409messages.delete
not_suspendable400identities.update
object_too_large413calendarObjects.put, addressbookObjects.put
over_quota507messages.append, messages.compose, messages.send, threads.reply, mta.submitOutbound, mta.deliverInbound
part_unresolvable400messages.send
part_walk_busy503deliveries.download
password_required400credentials.create, recovery.setAddress, recovery.removeAddress, recovery.createCodes, securityKeys.beginRegistration, securityKeys.remove, pickups.update
patch_required400labels.updateMessages, search.updateMatches
pattern_exists409patterns.create
pattern_limit400patterns.create
payload_too_large413accountAddressLists.importEntries, mailboxAddressLists.importEntries
pending_limit_reached409verifiedRecipients.add
permitted_recipients_requires_send400credentials.create
pickup_limit_reached409pickups.create
pickup_not_configured503pickups.create, pickups.update
posting_denied403mta.submitOutbound, mta.deliverInbound
posting_requires_group400routes.update
precondition_failed412calendarObjects.put, calendarObjects.delete, calendarObjects.move, addressbookObjects.put, addressbookObjects.delete, addressbookObjects.move
primary_address_required400identities.create
primary_address_route409routes.update, routes.delete
progress_requires_vtodo400calendarObjects.list, addressbookObjects.list
purge_in_progress409accounts.restore
rate_limited42923 methods, in 14 namespaces
receive_hold_changed409identities.update
receive_hold_not_enabled403identities.create, identities.update
receiving_disabled403messages.append, messages.compose, mta.checkRecipient, mta.submitOutbound, mta.deliverInbound
receiving_paused429messages.append, messages.compose, mta.checkRecipient, mta.submitOutbound, mta.deliverInbound
recently_unknown429mta.checkRecipient, mta.deliverInbound
recipient_limit_reached409verifiedRecipients.add
recipient_mail_unavailable503verifiedRecipients.add
recipient_not_permitted400, 403messages.send, messages.sendDraft, mta.checkRecipient, mta.submitOutbound
recipient_not_verified400, 403messages.send, mta.checkRecipient, mta.submitOutbound, mta.deliverInbound
recipient_verification_unavailable503verifiedRecipients.add
recovery_address_self400passwords.invite, recovery.setAddress
recovery_address_verified409passwords.invite
recovery_disabled403passwords.invite, recovery.setAddress
recovery_mail_unavailable503passwords.invite, recovery.setAddress
rendered_subject_too_long400templates.render, templates.send
rendered_too_large400templates.render, templates.send
resend_cooldown429verifiedRecipients.add, forwarding.addDestination
reserved403sieve.putScript, sieve.renameScript, sieve.deleteScript
reserved_delivery_id400threads.reply, templates.send
reserved_header400messages.compose, messages.send, templates.send
reserved_slug400templates.create
retention_too_short400accounts.setRetention, mailboxes.setRetention
route_changed409routes.create, routes.update, routes.addMember, routes.addMembers, routes.replaceMembers
route_exists409routes.create
run_cooldown429pickups.run
same_mailbox400messages.copy
schedule_failed409scheduled.reschedule, scheduled.cancel
scheduled_overwrite409calendarObjects.move, addressbookObjects.move
scheduling_backlog_full50710 methods of calendars, calendarObjects, addressbooks, addressbookObjects
scheduling_unavailable50310 methods of calendars, calendarObjects, addressbooks, addressbookObjects
script_active409sieve.deleteScript
search_offset_too_deep400search.fullText
search_term_too_long400calendarObjects.list, addressbookObjects.list, contacts.suggest
self_membership400routes.addMember, routes.addMembers, routes.replaceMembers
semantic_capacity503identities.create, identities.update
semantic_floor_with_opt_out400identities.update
semantic_misconfigured503search.similar
semantic_not_enabled403, 409identities.create, identities.update, search.semantic, search.similar
semantic_unavailable503search.semantic, search.similar
send_at_in_past400scheduled.reschedule
send_at_requires_save400messages.send
send_at_too_far400messages.send, scheduled.reschedule
send_receive_exclusive400domains.create, domains.update
sender_blocked403mta.checkRecipient, mta.submitOutbound, mta.deliverInbound
sender_not_local403mailboxes.checkSendAs, messages.send, messages.sendDraft, threads.reply, mta.submitOutbound
sender_not_owned403mailboxes.checkSendAs, messages.send, messages.sendDraft, threads.reply, mta.submitOutbound
sending_disabled403mailboxes.checkSendAs, messages.send, messages.sendDraft, threads.reply, mta.submitOutbound, templates.send
sending_not_writable403domains.update
sending_paused429mailboxes.checkSendAs, messages.send, messages.sendDraft, threads.reply, mta.submitOutbound, templates.send
service_unavailable409hostnames.set
slug_taken409templates.create
source_is_self400pickups.create, pickups.update, pickups.run
staging_missing503mta.submitOutbound
state_conflict412vacation.set
store_full507uploads.create, calendarObjects.put, addressbookObjects.put
store_metadata_full507messages.append, messages.compose, messages.send
subject_too_long400templates.setVariant, templates.render
submission_record_unavailable503messages.send, messages.sendDraft, threads.reply, mta.submitOutbound
suppression_moving503suppressions.list, suppressions.get, suppressions.remove
suspension_changed409identities.update
suspension_not_enabled403identities.update
system_credentials_required4039 methods of accounts, apiKeys, identities, mta, suppressions
system_key_in_secret409apiKeys.revoke
system_key_unexpirable400apiKeys.create
system_key_unscopable400apiKeys.create
system_keys_invalid409apiKeys.revoke
target_required400messages.updateMany, messages.copy, messages.untrash, messages.unjunk
template_invalid400templates.setVariant, templates.render, templates.send
template_limit_reached409templates.create
temporary_failure503280 methods, in 44 namespaces
text_required400templates.setVariant, templates.render
thread_context_required400messages.updateMany, messages.deleteMany, messages.copy
thread_too_large400messages.updateMany, messages.deleteMany, messages.copy, messages.untrash, messages.unjunk
too_large400, 413, 503102 methods, in 34 namespaces
too_many_collections409, 507calendars.create, calendars.restore, addressbooks.create, addressbooks.restore
too_many_destinations409forwarding.addDestination
too_many_items413calendars.import, addressbooks.import
too_many_labels409labels.create
too_many_objects507calendars.restore, calendarObjects.put, calendarObjects.restore, addressbooks.restore, addressbookObjects.put, addressbookObjects.restore
too_many_push_subscriptions429pushSubscriptions.create
too_many_recipients400, 403messages.send, messages.sendDraft, mta.submitOutbound
too_many_scheduled429messages.send, threads.reply
too_many_scripts409rules.set, sieve.putScript
too_many_subscribers429realtime.mailbox, realtime.pim
transition_in_progress409accounts.delete, accounts.restore
uid_conflict409calendarObjects.put, calendarObjects.move, calendarObjects.restore, addressbookObjects.put, addressbookObjects.move, addressbookObjects.restore
uid_validity_mismatch409labels.updateMessages, labels.updateMessagesById
uidmax_required400labels.updateMessages
unauthorized401308 methods, in 44 namespaces
unknown_account400apiKeys.create, domains.create, identities.create
unknown_address404mta.checkRecipient, mta.submitOutbound, mta.deliverInbound
unknown_domain400apiKeys.create, domains.create, domains.update, identities.create, identities.update, routes.create, patterns.create
unknown_label400, 404labels.updateMessages, messages.list, messages.deleteMany, messages.compose, messages.copy, search.updateMatches
unknown_mailbox400routes.create, routes.update, patterns.create, patterns.update
unknown_message400messages.send
unknown_part400messages.send
unparseable_message422messages.getContent, messages.getPart, messages.getInvitation, deliveries.download, calendars.respondToInvitation
unsatisfiable_recurrence400calendarObjects.put, addressbookObjects.put
unsupported_component409calendarObjects.put, calendarObjects.move, calendarObjects.restore, addressbookObjects.put, addressbookObjects.move, addressbookObjects.restore
unsupported_filter400search.query, search.updateMatches, search.snippets
unsupported_media_type415domains.setLogo
unsupported_sort400search.query
upgrade_required426realtime.mailbox, realtime.pim
upload_busy429uploads.create
upload_cleanup_pending503uploads.create
upstream_unavailable502accounts.delete, accounts.restore, domains.create, domains.update, domains.delete, hostnames.delete
username_not_in_scope400credentials.create
username_not_mailbox_address400credentials.create
username_required400credentials.create
username_taken409credentials.create
validation_failed400140 methods, in 33 namespaces
vanity_hosts_disabled403hostnames.set
variant_limit_reached409templates.setVariant
verification_unavailable503domains.create
version_conflict412identities.setPreferences
visibility_conflict409calendars.update, addressbooks.update
web_push_not_configured403pushSubscriptions.create
webauthn_failed400securityKeys.finishRegistration
webhook_format_unavailable400identities.create, mailboxes.setMessageWebhook, routes.create, routes.update, patterns.create, patterns.update
window_too_large413freeBusy.get, freeBusy.getMany
without_address_has_address400identities.create
wrong_kind409calendarObjects.move, addressbookObjects.move