[metadata]
color-scheme: dark light
description: List of general and specific errors you may encounter when using the REST API.
googlebot: index, max-video-preview:-1, max-image-preview:large, max-snippet:-1
initiator-trace: 00-77c3767f4ac05967521f92de83ba2536-1501bb17a71f6a1b-01
robots: index, follow
theme-color: #0a0a0a
trace-attributes: {"next.appdir":true}
viewport: width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover

[canonical-links]
https://vercel.com/docs/rest-api/errors

[document-links]
/home
AI Apps: /solutions/ai-apps
AI Gateway: /ai-gateway
AI Gateway: /docs/ai-gateway
AI Integrations: /docs/agent-resources/integrations-for-models
AI SDK: /ai-sdk
AI SDK: /docs/ai-sdk
APIs & SDKs: /docs/rest-api
About: /about
Academy: /academy
Acceptable Use Policy: /legal/acceptable-use-policy
Agent Skills: https://skills.sh
All frameworks: /docs/frameworks
Articles: /i
Blog ↗: https://vercel.com/blog
Blog: /blog
Bot ID: /botid
Bot Management: /docs/bot-management
Bot Management: /security/bot-management
BotID: /docs/botid
CI/CD: /products/previews
CLI: /docs/cli
Careers: /careers
Changelog ↗: https://vercel.com/changelog
Changelog: /changelog
Chat SDK New: /chat
Commerce: /solutions/composable-commerce
Community ↗: https://community.vercel.com
Community: https://community.vercel.com
Compliance: /docs/security/compliance
Connect New: /connect
Container Registry: /docs/container-registry
Content Delivery: /cdn
Cookie Policy: /legal/cookie-policy
Customers: /customers
DPA: /legal/dpa
Delivery Network: /docs/cdn
Deployment Protection: /docs/deployment-protection
Deployments: /docs/deployments
Design Engineers: /solutions/design-engineering
Docs: /docs
Domains: /docs/domains
Domains: /domains
Enterprise: /enterprise
Errors: /docs/rest-api/errors
Events: /events
FastAPI: /docs/frameworks/backend/fastapi
Feature Flags: /docs/flags
Firewall: /docs/vercel-firewall
Flags SDK: /docs/flags/flags-sdk-reference
Fluid Compute: /fluid
Functions: /docs/functions
Getting Started: /docs/getting-started-with-vercel
GitHub: https://github.com/vercel
Help: /help
Instagram: https://www.instagram.com/vercel/
Integrations: /docs/integrations
Knowledge Base: /kb
Legal (all documents): /legal
LinkedIn: https://linkedin.com/company/vercel
Log In: /login
Marketing Sites: /solutions/marketing-sites
Marketplace: /marketplace
Microfrontends: /docs/microfrontends
Next.js: /frameworks/nextjs
Nitro: /docs/frameworks/backend/nitro
Nuxt: /docs/frameworks/full-stack/nuxt
OAuth2 related endpoint: /docs/integrations/vercel-api-integrations#create-an-access-token
Observability: /docs/observability
Observability: /products/observability
Open Source Program: /open-source-program
Overview: /docs/rest-api
Partner Finder: /partners/solution-partners
Passport New: /passport
Platform Engineers: /solutions/platform-engineering
Platform Security: /security
Platforms: /solutions/multi-tenant-saas
Press: /press
Pricing: /pricing
Privacy Policy: /legal/privacy-policy
Queues SDK New: /docs/queues/sdk
Sandbox: /docs/sandbox
Sandbox: /sandbox
Shipped on Vercel: /shipped
Sign Up: /signup
Startups: /startups
Status: https://vercel-status.com
Storage: /docs/storage
Streamdown: https://streamdown.ai
SvelteKit: /docs/frameworks/full-stack/sveltekit
Tanstack Start: /docs/frameworks/full-stack/tanstack-start
Templates: /templates
Terms of Service: /legal/terms
Toolbar: /docs/vercel-toolbar
Trust Center: https://security.vercel.com
Turborepo: /solutions/turborepo
Vercel + AWS: /partners/aws
Vercel Agent: /agent
Vercel Agent: /docs/agent
Vercel Drop New: /drop
Vercel MCP: /docs/mcp
Vercel Plugin New: /plugin
Vercel REST API: /docs
Vercel SDK: /docs/rest-api/sdk
WAF: /security/web-application-firewall
Web Apps: /solutions/web-apps
Workflow SDK New: /workflows
Workflow: /docs/workflows
Workflows: /workflows
X: https://x.com/vercel
YouTube: https://youtube.com/@VercelHQ
any valid DNS record: https://en.wikipedia.org/wiki/List_of_DNS_record_types
contact support: https://vercel.com/help
eve New: /eve
eve New: https://eve.dev/
v0 ↗: https://v0.app
v0: https://v0.app
xmcp: /docs/frameworks/backend/xmcp

[structured-data]
{"@context":"https://schema.org","@type":"WebSite","name":"Vercel Documentation","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://lishhsx6kmthaacj.public.blob.vercel-storage.com/vercel-wordmark.svg"},"name":"Vercel Inc.","sameAs":["https://x.com/vercel","https://github.com/vercel/vercel","https://www.linkedin.com/company/vercel/","https://bsky.app/profile/vercel.com"],"url":"https://vercel.com/"},"url":"https://vercel.com/docs"}

[content]
Errors | Vercel REST API
Skip to content
Copy Logo as SVG
Copy Wordmark as SVG
Brand Guidelines
Docs
Build
Build with AI
AI Gateway
AI SDK
Sandbox
Container Registry
Workflow
Vercel Agent
v0
↗
Vercel MCP
AI Integrations
Deploy & scale
Deployments
CLI
Functions
Delivery Network
Storage
Integrations
Microfrontends
Domains
Operate & protect
Firewall
Observability
Feature Flags
Toolbar
Bot Management
BotID
Deployment Protection
Compliance
Learn
Resources
Changelog
↗
Blog
↗
Community
↗
Knowledge Base
APIs & SDKs
Templates
Getting Started
Ask AI
Log In
Sign Up
Build
Build with AI
AI Gateway
AI SDK
Sandbox
Container Registry
Workflow
Vercel Agent
v0
↗
Vercel MCP
AI Integrations
Deploy & scale
Deployments
CLI
Functions
Delivery Network
Storage
Integrations
Microfrontends
Domains
Operate & protect
Firewall
Observability
Feature Flags
Toolbar
Bot Management
BotID
Deployment Protection
Compliance
Learn
Resources
Changelog
↗
Blog
↗
Community
↗
Knowledge Base
APIs & SDKs
Templates
Getting Started
Ask AI
Sign Up
Log In
Vercel REST API
Overview
Errors
Access Groups
Ai Gateway
Aliases
Artifacts
Authentication
Billing
Bulk Redirects
Certs
Checks V2
Connect
Deployments
DNS
Domains
Domains Registrar
Drains
Edge Cache
Environment
Feature Flags
Global Config
Integrations
Logs
Marketplace
Microfrontends
Networking
Observability
Project Routes
Projectmembers
Projects
Rolling Release
Sandboxes
Security
Static Ips
Storage
Teams
User
VCR
Web Analytics
Webhooks
APIs & SDKs
Vercel REST API
Errors
List of general and specific errors you may encounter when using the REST API.
Generic errors
These error codes are consistent for all endpoints.
Forbidden
You're not authorized to use the endpoint. This usually happens due to missing a user token.
Similar to the HTTP 403 Forbidden error.
1
{
2
"error"
:
{
3
"code"
:
"forbidden"
,
4
"message"
:
"Not authorized"
5
}
6
}
Rate limited
You exceeded the maximum allotted requests.
The limit of requests is per endpoint basis so you can continue using other endpoints even if some of them give you this error.
1
{
2
"error"
:
{
3
"code"
:
"rate_limited"
,
4
"message"
:
"The rate limit of 6 exceeded for 'api-www-user-update-username'. Try again in 7 days"
,
5
"limit"
:
{
6
"remaining"
:
0
,
7
"reset"
:
1571432075
,
8
"resetMs"
:
1571432075563
,
9
"total"
:
6
10
}
11
}
12
}
Bad request
There was an error with the request, the
error.message
would contain information about the issue.
1
{
2
"error"
:
{
3
"code"
:
"bad_request"
,
4
"message"
:
"An english description of the error that just occurred"
5
}
6
}
Internal server error
This error is similar to the HTTP 500 Internal Server Error error code.
1
{
2
"error"
:
{
3
"code"
:
"internal_server_error"
,
4
"message"
:
"An unexpected internal error occurred"
5
}
6
}
Resource not found
The requested resource could not be found.
1
{
2
"error"
:
{
3
"code"
:
"not_found"
,
4
"message"
:
"Could not find the RESOURCE: ID"
5
}
6
}
Method unknown
The endpoint you're requesting does not handle the method you defined. The error message will contain the methods the endpoint responds to.
1
{
2
"error"
:
{
3
"code"
:
"method_unknown"
,
4
"message"
:
"This endpoint only responds to METHOD"
5
}
6
}
Deployment errors
These error codes can happen when using any deployment related endpoint.
Missing files
Some of the files you defined when creating the deployment are missing.
1
{
2
"error"
:
{
3
"code"
:
"missing_files"
,
4
"message"
:
"Missing files"
,
5
"missing"
:
[
]
6
}
7
}
No files in the deployment
You tried to create an empty deployment.
1
{
2
"error"
:
{
3
"code"
:
"no_files"
,
4
"message"
:
"No files in the deployment"
5
}
6
}
Too many environment variables
The limit of environment variables per deployment is 100 and you defined more. The error message indicates the amount you defined.
#
is your number of variables.
1
{
2
"error"
:
{
3
"code"
:
"env_too_many_keys"
,
4
"message"
:
"Too many env vars have been supplied (100 max allowed, but got #)"
5
}
6
}
Environment variable key with invalid characters
Some environment variable name contains an invalid character. The only valid characters are letters, digits and
_
.
The error message will contain the
KEY
with the problem.
1
{
2
"error"
:
{
3
"code"
:
"env_key_invalid_characters"
,
4
"message"
:
"The env key \"KEY\" contains invalid characters. Only letters, digits and `_` are allowed"
,
5
"key"
:
"KEY"
6
}
7
}
Environment variable key with a long name
An environment variable name is too long, the maximum permitted name is 256 characters.
The error message contains the environment
KEY
.
1
{
2
"error"
:
{
3
"code"
:
"env_key_invalid_length"
,
4
"message"
:
"The env key \"KEY\" exceeds the 256 length limit"
,
5
"key"
:
"KEY"
6
}
7
}
Environment variable value with a long name
An environment variable value contains a value too long, the maximum permitted value is 65536 characters.
The error message contains the environment
KEY
.
1
{
2
"error"
:
{
3
"code"
:
"env_value_invalid_length"
,
4
"message"
:
"The env value for \"KEY\" exceeds the 65536 length limit"
,
5
"key"
:
"KEY"
,
6
"value"
:
"VALUE"
7
}
8
}
Environment variable value is an object without UID
The value of an environment variable is an object but it doesn't have a
uid
.
The error message contains the environment
KEY
which has the error.
1
{
2
"error"
:
{
3
"code"
:
"env_value_invalid_type_missing_uid"
,
4
"message"
:
"The env key \"KEY\" passed an object as a value with no `uid` key"
5
}
6
}
Environment variable value is an object with unknown props
The value of an environment variable is an object with unknown attributes, it can only have a
uid
key inside the object.
1
{
2
"error"
:
{
3
"code"
:
"env_value_invalid_type_unknown_props"
,
4
"message"
:
"The env key \"KEY\" passed an object with unknown properties. Only `uid` is allowed when passing an object"
5
}
6
}
Environment variable value with an invalid type
An environment variable value passed is of an unsupported type.
The error message contains the environment
KEY
.
1
{
2
"error"
:
{
3
"code"
:
"env_value_invalid_type"
,
4
"message"
:
"The env key \"KEY\" passed an unsupported type for its value"
,
5
"key"
:
"KEY"
6
}
7
}
Not allowed to access a secret
You're trying to use a secret but you don't have access to it.
1
{
2
"error"
:
{
3
"code"
:
"env_secret_forbidden"
,
4
"message"
:
"Not allowed to access secret \"NAME\""
,
5
"uid"
:
"UID"
6
}
7
}
Missing secret
You're trying to use a secret as an environment value and it doesn't exist.
1
{
2
"error"
:
{
3
"code"
:
"env_secret_missing"
,
4
"message"
:
"Could not find a secret by uid \"UID\""
,
5
"uid"
:
"UID"
6
}
7
}
Domain errors
These error codes can happen when using any domain related endpoint.
Domain forbidden
You don't have access to the domain, this usually means the domain is owned by another account or team.
The domain is specified in the message and the
DOMAIN
key.
1
{
2
"error"
:
{
3
"code"
:
"forbidden"
,
4
"message"
:
"You don't have access to \"DOMAIN\""
,
5
"domain"
:
"DOMAIN"
6
}
7
}
Domain not found
The domain name could not be found in the system.
1
{
2
"error"
:
{
3
"code"
:
"not_found"
,
4
"message"
:
"Domain name not found"
5
}
6
}
Missing domain name
The domain name wasn't specified in the URL. This means you tried to use an endpoint which requires you to define the domain name in the URL but didn't define it.
1
{
2
"error"
:
{
3
"code"
:
"missing_name"
,
4
"message"
:
"The URL was expected to include the domain name. Example: /domains/google.com"
5
}
6
}
Conflicting aliases
You must remove the aliases described in the error before removing the domain.
The aliases are specified in the
ALIASES
key.
1
{
2
"error"
:
{
3
"code"
:
"conflict_aliases"
,
4
"message"
:
"The following aliases must be removed before removing the domain: ALIASES"
,
5
"aliases"
:
[
"ALIASES"
]
6
}
7
}
Not modified
When trying to modify a domain nothing was required to change.
1
{
2
"error"
:
{
3
"code"
:
"not_modified"
,
4
"message"
:
"Nothing to do"
5
}
6
}
Missing name for domain
When trying to add a domain the name wasn't present in the request body.
1
{
2
"error"
:
{
3
"code"
:
"missing_name"
,
4
"message"
:
"The `name` field in the body was expected but is not present in the body payload. Example value: `example.com`"
5
}
6
}
Invalid name for domain
The domain name defined in the request body is invalid.
The name is specified in the error as the
NAME
key.
1
{
2
"error"
:
{
3
"code"
:
"invalid_name"
,
4
"message"
:
"The `name` field contains an invalid domain name (\"NAME\")"
,
5
"name"
:
"NAME"
6
}
7
}
Custom domain needs a plan upgrade
To add a custom domain to your account or team you need to upgrade to a paid plan.
1
{
2
"error"
:
{
3
"code"
:
"custom_domain_needs_upgrade"
,
4
"message"
:
"Domain name creation requires a premium account."
5
}
6
}
Domain already exists
The domain name you're trying to add already exists.
The domain name and its current ID are received in the
NAME
and
DOMAIN_ID
keys.
1
{
2
"error"
:
{
3
"code"
:
"not_modified"
,
4
"message"
:
"The domain \"NAME\" already exists"
,
5
"name"
:
"NAME"
,
6
"uid"
:
"DOMAIN_ID"
7
}
8
}
Can't create the domain
The domain name can't be created. Most likely it couldn't be verified.
1
{
2
"error"
:
{
3
"code"
:
"forbidden"
,
4
"message"
:
"You don't have permission to create a domain"
5
}
6
}
Failed to add domain after purchase
The domain was purchased but there was an error adding it to your account. Please
contact support
.
1
{
2
"error"
:
{
3
"code"
:
"failed_to_add_domain"
,
4
"message"
:
"The domain was bought but couldn't be added."
5
}
6
}
Unable to determine the domain price
The price of a domain could not be determined.
1
{
2
"error"
:
{
3
"code"
:
"service_unavailable"
,
4
"message"
:
"Failed to determine the domain price"
5
}
6
}
Domain price mismatch
The
expectedPrice
supplied in the request body does not match the actual domain price, which is specified in the
actualPrice
key.
1
{
2
"error"
:
{
3
"code"
:
"price_mismatch"
,
4
"message"
:
"The expected price does not match the actual price"
,
5
"price"
:
"ACTUAL_PRICE"
6
}
7
}
Domain is not available
The domain name is not available to be purchased.
1
{
2
"error"
:
{
3
"code"
:
"not_available"
,
4
"message"
:
"Domain is not available"
5
}
6
}
Invalid domain name
The domain name or TLD is invalid or not supported.
1
{
2
"error"
:
{
3
"code"
:
"invalid_domain"
,
4
"message"
:
"Invalid domain or TLD"
5
}
6
}
Missing DNS record name
The DNS record key
name
is required and was not provided. It could be
any valid DNS record
.
1
{
2
"error"
:
{
3
"code"
:
"missing_type"
,
4
"message"
:
"Missing `type` parameter"
5
}
6
}
DNS errors
These error codes can happen when using any DNS related endpoint.
Missing DNS record name
The DNS record key
name
is required and was not provided. It should be either a subdomain or
@
for the domain itself.
1
{
2
"error"
:
{
3
"code"
:
"missing_name"
,
4
"message"
:
"Missing `name` parameter"
5
}
6
}
Missing DNS record type
The DNS record key
type
is required and was not provided. It could be
any valid DNS record
.
1
{
2
"error"
:
{
3
"code"
:
"missing_type"
,
4
"message"
:
"Missing `type` parameter"
5
}
6
}
OAuth2 errors
These errors can occur when using any
OAuth2 related endpoint
.
Client not found
The OAuth2 client ID could not be found or doesn't exist.
1
{
2
"error"
:
{
3
"code"
:
"not_found"
,
4
"message"
:
"OAuth client not found: CLIENT_ID"
5
}
6
}
On this page
Generic errors
Forbidden
Rate limited
Bad request
Internal server error
Resource not found
Method unknown
Deployment errors
Missing files
No files in the deployment
Too many environment variables
Environment variable key with invalid characters
Environment variable key with a long name
Environment variable value with a long name
Environment variable value is an object without UID
Environment variable value is an object with unknown props
Environment variable value with an invalid type
Not allowed to access a secret
Missing secret
Domain errors
Domain forbidden
Domain not found
Missing domain name
Conflicting aliases
Not modified
Missing name for domain
Invalid name for domain
Custom domain needs a plan upgrade
Domain already exists
Can't create the domain
Failed to add domain after purchase
Unable to determine the domain price
Domain price mismatch
Domain is not available
Invalid domain name
Missing DNS record name
DNS errors
Missing DNS record name
Missing DNS record type
OAuth2 errors
Client not found
Agent Stack
AI SDK
AI Gateway
Sandbox
Workflows
Connect
New
Passport
New
eve
New
Core Platform
CI/CD
Content Delivery
Fluid Compute
Observability
Security
Platform Security
WAF
Bot Management
Bot ID
Tools
Vercel Drop
New
Vercel Agent
Vercel Plugin
New
Agent Skills
Next.js
Domains
v0
Frameworks
eve
New
Nuxt
SvelteKit
Nitro
Turborepo
Tanstack Start
FastAPI
xmcp
All frameworks
SDKs
Vercel SDK
Workflow SDK
New
Flags SDK
Chat SDK
New
Queues SDK
New
Streamdown
Build
AI Apps
Web Apps
Marketing Sites
Platforms
Commerce
Platform Engineers
Design Engineers
Learn
Docs
Blog
Changelog
Knowledge Base
Academy
Articles
Community
Explore
Customers
Marketplace
Templates
Partner Finder
Vercel + AWS
Company
About
Careers
Press
Events
Startups
Shipped on Vercel
Open Source Program
Enterprise
Pricing
Help
Legal & Trust
Privacy Policy
Terms of Service
Cookie Policy
DPA
Acceptable Use Policy
Legal (all documents)
Trust Center
Status
Cookie Preferences
Social
GitHub
X
LinkedIn
YouTube
Instagram
