Reference
8 min read

Vercel REST API Errors

The Vercel REST API is a REST-styled API that gives full control over the entire Vercel platform.
Table of Contents

These error codes are consistent for all endpoints.

You're not authorized to use the endpoint. This usually happens due to missing an user token.

Similar to the HTTP 403 Forbidden error.
error-response-forbidden
{
  "error": {
    "code": "forbidden",
    "message": "Not authorized"
  }
}

You exceeded the maximum allotted requests.

The limit of request is per endpoint basis so you could continue using another endpoints even if some of them give you this error.

error-response-rate-limited
{
  "error": {
    "code": "rate_limited",
    "message": "The rate limit of 6 exceeded for 'api-www-user-update-username'. Try again in 7 days",
    "limit": {
      "remaining": 0,
      "reset": 1571432075,
      "resetMs": 1571432075563,
      "total": 6
    }
  }
}

There was an error with the request, the error.message would contain information about the issue.

error-response-bad-request
{
  "error": {
    "code": "bad_request",
    "message": "An english description of the error that just occurred"
  }
}

This errors is similar to the HTTP 500 Internal Server Error error code.

error-response-internal-server-error
{
  "error": {
    "code": "internal_server_error",
    "message": "An unexpected internal error occurred"
  }
}

The requested resource could not be found

error-response-not-Found
{
  "error": {
    "code": "not_found",
    "message": "Could not find the RESOURCE: ID"
  }
}

The endpoint you're requesting does not handle the method you defined. The error message will contain the methods the endpoint responds to.

error-response-method-unknown
{
  "error": {
    "code": "method_unknown",
    "message": "This endpoint only responds to METHOD"
  }
}

These error code could happen when using any deployment related endpoint.

Some of the files you defined when creating the deployment are missing.

error-response-missing-files
{
  "error": {
    "code": "missing_files",
    "message": "Missing files",
    "missing": []
  }
}

You tried to create an empty deployment.

error-response-no-files
{
  "error": {
    "code": "no_files",
    "message": "No files in the deployment"
  }
}

The limit of environment variables per deployment is 100 and you defined more. The error message indicates the amount you define.

error-response-too-many-env-keys
{
  "error": {
    "code": "env_too_many_keys",
    "message": "Too many env vars have been supplied (100 max allowed, but got #)"
  }
}

# is your number of variables.

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.

error-response-env-key-invalid-characters
{
  "error": {
    "code": "env_key_invalid_characters",
    "message": "The env key "KEY" contains invalid characters. Only letters, digits and \`_\` are allowed",
    "key": KEY
  }
}

An environment variable name is too long, the maximum permitted name is 256 characters.

The error message contains the environment KEY.

error-response-env-key-invalid-length
{
  "error": {
    "code": "env_key_invalid_length",
    "message": "The env key "KEY" exceeds the 256 length limit",
    "key": KEY
  }
}

An environment variable value contains a value too long, the maximum permitted value is 65536 characters.

The error message contains the environment KEY.

error-response-env-value-invalid-length
{
  "error": {
    "code": "env_value_invalid_length",
    "message": "The env value for "KEY" exceeds the 65536 length limit",
    "key": KEY,
    "value": VALUE
  }
}

The value of an environment variable is object but it doesn't have a uid.

The error message contains the environment KEY which has the error.

error-response-env-value-invalid-type
{
  "error": {
    "code": "env_value_invalid_type_missing_uid",
    "message": "The env key "KEY" passed an object as a value with no \`uid\` key"
  }
}

The value of an environment variable is an object with unknown attributes, it only can have a uid key inside the object.

error-response-env-value-invalid-type
{
  "error": {
    "code": "env_value_invalid_type_unknown_props",
    "message": "The env key "KEY" passed an object with unknown properties. Only \`uid\` is allowed when passing an object"
  }
}

An environment variable value passed is of an unsupported type.

The error message contains the environment KEY.

error-response-env-value-invalid-type
{
  "error": {
    "code": "env_value_invalid_type",
    "message": "The env key "KEY" passed an unsupported type for its value",
    "key": KEY
  }
}

You're trying to use a secret but you don't have access to it.

error-response-secret-forbidden
{
  "error": {
    "code": "env_secret_forbidden",
    "message": "Not allowed to access secret \\"NAME\\"",
    "uid": UID
  }
}

You're trying to use a secret as an environment value and it doesn't exists.

error-response-secret-missing
{
  "error": {
    "code": "env_secret_missing",
    "message": "Could not find a secret by uid "UID"",
    "uid": UID
  }
}

These error code could happen when using any domains related endpoints.

You don't have access to the domain, this usually mean this domains is owned by another account or team.

The domain is specified in the message and the DOMAIN key.

error-response-forbidden
{
  "error": {
    "code": "forbidden",
    "message": "You don't have access to \\"DOMAIN\\"",
    "domain": DOMAIN
  }
}

The domain name could not be found in our system. Try to add it first.

error-response-not-found
{
  "error": {
    "code": "not_found",
    "message": "Domain name not found"
  }
}

The domain name wasn't specified in the URL. This means you tried to use an endpoint which require you to define the domain name in the URL but didn't defined it.

error-response-missing-name
{
  "error": {
    "code": "missing_name",
    "message": "The URL was expected to include the domain name. Example: /domains/google.com"
  }
}

You must remove the certificates described in the error before removing the domains.

The certificates are specified in the CERT_CNS key.

error-response-conflict-certs
{
  "error": {
    "code": "conflict_certs",
    "message": "The following certificates must be removed before removing the domain: CERT_CNS",
    "certCNs": CERT_CNS
  }
}

You must remove the aliases described in the error before removing the domains.

The aliases are specified in the ALIASES key.

error-response-conflict-alias
{
  "error": {
    "code": "conflict_aliases",
    "message": "The following aliases must be removed before removing the domain: ALIASES",
    "aliases": ALIASES
  }
}

When trying to modify a domain nothing was required to change.

error-response-not-modified
{
  "error": {
    "code": "not_modified",
    "message": "Nothing to do"
  }
}

When trying to add a domain the name wasn't present in the request body.

error-response-missing-name
{
  "error": {
    "code": "missing_name",
    "message": "The `name` field in the body was expected but is not present in the body payload. Example value: `example.com`"
  }
}

The domain name defined in the request body is invalid.

The name is specified in the error as the NAME key.

error-response-invalid-name
{
  "error": {
    "code": "invalid_name",
    "message": "The \`name\` field contains an invalid domain name ("NAME")",
    "name": NAME
  }
}

In order to add a custom domain to your account or team you need to upgrade to a paid plan.

error-response-domain-needs-upgrade
{
  "error": {
    "code": "custom_domain_needs_upgrade",
    "message": "Domain name creation requires a premium account."
  }
}

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.

error-response-not-modified
{
  "error": {
    "code": "not_modified",
    "message": "The domain "NAME" already exists",
    "name": NAME,
    "uid": DOMAIN_ID
  }
}

The domain name can't be created. Most probably it couldn't be verified.

error-response-forbidden
{
  "error": {
    "code": "forbidden",
    "message": "You don't have permission to create a domain"
  }
}

We were able to purchase a domain for you but we had an error when trying to add it to your account. Please contact us on Contact Support.

error-response-failed-add-domain
{
  "error": {
    "code": "failed_to_add_domain",
    "message": "The domain was bought but couldn't be added.
  }
}

We're unable to determine the domain price of a domain.

error-response-service-unavailable
{
  "error": {
    "code": "service_unavailable",
    "message": "Failed to determine the domain price"
  }
}

The expectedPrice supplied in the request body does not match the actual domain price, which is specified in the actualPrice key.

error-response-price-mismatch
{
  "error": {
    "code": "price_mismatch",
    "message": "The expected price does not match the actual price",
    "price": ACTUAL_PRICE
  }
}

The domain name is not available to be purchased.

error-response-not-available
{
  "error": {
    "code": "not_available",
    "message": "Domain is not available"
  }
}

The domain name or TLD is invalid or not supported.

error-response-invalid-domain
{
  "error": {
    "code": "invalid_domain",
    "message": "Invalid domain or TLD"
  }
}

The DNS record key name is required and was not provided. It could be any valid DNS record.

error-response-missing-type
{
  "error": {
    "code": "missing_type",
    "message": "Missing `type` parameter"
  }
}

These error code could happen when using any DNS related endpoint.

The DNS record key name is required and was not provided. It should be either a subdomain or @ for the domain itself.

error-response-missing-Name
{
  "error": {
    "code": "missing_name",
    "message": "Missing `name` parameter"
  }
}

The DNS record key name is required and was not provided. It could be any valid DNS record.

error-response-missing-type
{
  "error": {
    "code": "missing_type",
    "message": "Missing `type` parameter"
  }
}

These errors could occur when using any OAuth2 related endpoint.

The OAuth2 client ID could not be found or doesn't exist.

error-response-not-found
{
  "error": {
    "code": "not_found",
    "message": "OAuth client doesn't not found: CLIENT_ID"
  }
}
Last updated on April 25, 2024