All Products
Search
Document Center

API Gateway:Error codes

Last Updated:Jan 05, 2023

This topic describes the error codes of API Gateway.

1. Error codes for API Gateway instances of the VPC type

The error codes described in this section apply only to shared instances and dedicated instances of the VPC type. For more information about error codes for instances of the classic network type, see the section "Error codes for API Gateway instances of the classic network type" in this topic.

  • If a client receives a response in which the X-Ca-Error-Code header is not empty, the HTTP status code is returned by API Gateway. An error code is six characters in length. For more information, see the following table. The X-Ca-Error-Message header indicates the detailed error message in the specific scenario.

  • If the X-Ca-Error-Code header is empty, the HTTP status code is generated by a backend service. API Gateway passes through the error information from the backend service.

Error code

HTTP status code

Message

Description

I400HD

400

Invalid Header `${HeaderName}` ${Reason}

The error message returned because an HTTP request header is invalid.

I400MH

400

Header `${HeaderName}` is Required

The error message returned because an HTTP request header is missing.

I400BD

400

Invalid Body: ${Reason}

The error message returned because the HTTP request body is invalid.

I400PA

400

Invalid Request Path `${Reason}`

The error message returned because the HTTP request path is invalid.

I405UM

405

Unsupported Method `${Reason}`

The error message returned because the HTTP request method is not supported.

I400RU

400

Invalid Request Uri `${Reason}`

The error message returned because the HTTP request URL is invalid.

I403PT

403

Invalid protocol ${Protocol} unsupported

The error message returned because the protocol is not supported based on the API configurations. Check the API configurations.

I413RL

413

Request body too Large

The error message returned because the request body is too large.

I413UL

413

Request URL too Large

The error message returned because the request URL is too long.

I400CT

400

Invalid Content-Type: `${Reason}`

The error message returned because the Content-Type value is invalid.

I404DO

404

Invalid Domain `${DomainName}`

The error message returned because the domain name in the request is unknown.

I410GG

410

Group's instance invalid

The error message returned because an invalid instance is requested. The group may not belong to the specified instance.

I400SG

400

Invalid Stage

The error message returned because an unknown environment is requested.

I404NF

404

API not found ${Reason}

The error message returned because the API is not found based on the Path and Method values of the request.

X400PM

400

Invalid plugin meta ${PluginName} ${Reason}

The error message returned because the metadata of the plug-in is invalid. Submit a ticket to contact Alibaba Cloud technical support.

X500ED

500

Expired api definition

The error message returned because the specified API metadata definition is invalid. Submit a ticket to contact Alibaba Cloud technical support.

X500AM

500

Invalid Api Meta, try deploy again or contact us via ticket

The error message returned because the specified API metadata definition is invalid. Submit a ticket to contact Alibaba Cloud technical support.

X403DG

403

Bad Domain or Group: ${Reason}

The error message returned because the group data is invalid. Submit a ticket to contact Alibaba Cloud technical support.

B451DO

451

Unavailable Domain for Legal Reasons

The error message returned because the domain name does not comply with the requirements of relevant laws or regulations.

B451GO

451

Unavailable Group for Legal Reasons

The error message returned because the group does not comply with the requirements of relevant laws or regulations.

B403OD

403

Provider Account Overdue

The error message returned because the API provider has overdue payments.

A401AC

401

Invalid AppCode ${Reason}

The error message returned because the AppCode is not found when you perform an authorization in AppCode mode.

A400IK

400

Invalid AppKey

The error message returned because the AppKey is not found when you perform an authorization by using a key-secret pair.

A403IS

403

Invalid Signature, Server StringToSign:`${StringToSign}`

The error message returned because the signature is invalid. For more information, see the Request signature topic.

A403EP

403

App authorization expired

The error message returned because the authorization expired.

A403PR

403

Plugin Authorization Needed

The error message returned because plug-in authorization is required.

A400MA

400

Need authorization, `X-Ca-Key` or `Authorization: APPCODE ...` is required

The error message returned because authorization in AppCode mode or by using a key-secret pair is required.

I400I5

400

Invalid Content-MD5 ${Reason}

The error message returned because the Content-MD5 value is invalid.

I400NC

400

X-Ca-Nonce is required

The error message returned because the X-Ca-Nonce header is not provided after you select Force Nonce Check (Anti Replay by X-Ca-Nonce).

S403NU

403

Nonce Used

The error message returned because a replay attack is detected. The X-Ca-Nonce header in the request has been used.

S403TE

403

X-Ca-Timestamp is expired

The error message returned because the timestamp specified by the X-Ca-Timestamp header expired.

I400MP

400

Parameter `${ParameterName}` is required

The error message returned because a required parameter is not provided based on the API configurations.

I400IP

400

Invalid parameter `${ParameterName}` ${Reason}

The error message returned because the value of a parameter is invalid based on the API configurations.

I400JR

400

JWT required

The error message returned because JSON Web Token (JWT)-related parameters are not found.

S403JI

403

Claim `jti` is required when `preventJtiReplay:true`

The error message returned because no valid jti claim is included in the request when the preventJtiReplay parameter is set to true in a JWT authentication plug-in.

A403SV

403

Claim `jti` in JWT is used

The error message returned because the jti claim that is included in the request has been used when the preventJtiReplay parameter is set to true in a JWT authentication plug-in.

I400JD

400

JWT Deserialize Failed: `${Token}`

The error message returned because the JWT in the request cannot be parsed.

A403JT

403

Invalid JWT: ${Reason}

The error message returned because the JWT in the request is invalid.

A403JK

403

No matching JWK, `${kid}` not found

The error message returned because no JWK matches the kid configured in the JWT in the request.

A403JE

403

JWT is expired at `${Date}`

The error message returned because the JWT in the request expired.

I400JP

400

Invalid JWT plugin config: ${JWT}

The error message returned because the JWT authentication plug-in is incorrectly configured.

A403OL

403

OAuth2 Login failed: ${Reason}

A403OU

403

OAuth2 Get User Info failed: ${Reason}

A401OT

401

Invalid OAuth2 Access Token

A401OM

401

OAuth2 Access Token is required

T429ID

429

Throttled by INNER DOMAIN Flow Control, ${Domain} is a test domain, only 1000 requests per day

The error message returned because a system-assigned second-level domain name is used to make API calls. You can make 100 API calls per day in regions outside the Chinese mainland and 1,000 API calls per day in regions in the Chinese mainland by using the system-assigned second-level domain name. You can bind an independent domain name to make an unlimited number of API calls.

T429IN

429

Throttled by INSTANCE Flow Control

The error message returned because throttling is triggered for the current instance.

T429GR

429

Throttled by GROUP Flow Control

The error message returned because throttling is triggered for the current group.

T429PA

429

Throttled by API Flow Control

The error message returned because the default API-level throttling policy defined in the throttling plug-in is triggered.

T429PR

429

Throttled by PLUGIN Flow Control

The error message returned because the special throttling policy defined in the throttling plug-in is triggered.

T429SR

429

Throttled by SERVER Flow Control

T429MR

429

Too Many Requests, throttle by `${Description}`

A403IP

403

Access denied by IP Control Policy

The error message returned because access is denied by the IP address-based access control plug-in.

A403IN

403

Access from internet is disabled ${Reason}

The error message returned because you are not allowed to call APIs or access API groups over the Internet.

A403VN

403

Access from invalid VPC is disabled

The error message returned because access over the specified VPC is denied.

A403AC

403

Access Control Forbidden by ${RuleName}

The error message returned because access is denied by the access control plug-in.

A403CO

403

Cross origin resource forbidden ${Domain}

The error message returned because access is denied by the cross-origin resource sharing (CORS) plug-in.

I404CO

404

Cross origin resource not found ${Method} - ${Path}

The error message returned because the API definition is not found based on the Path and Method values of the request that is pre-checked by the CORS plug-in.

I404CH

404

Content not cached, with `Cache-Control:only-if-cached`

I404NR

404

${Resource} not found

I404SR

404

Stage route missing: ${Reason}

B403MO

403

Api Market Subscription overdue

The error message returned because the API provider has overdue payments.

B403MQ

403

Api Market Subscription quota exhausted

The error message returned because the API quota you purchased in Alibaba Cloud Marketplace has been exhausted.

B403ME

403

Api Market Subscription expired

The error message returned because the subscribed API service expired.

B403MI

403

Api Market Subscription invalid

The error message returned because the subscribed API service is invalid.

D504RE

504

Backend domain `${Domain}` resolve failed

The error message returned because the domain name cannot be resolved at the backend.

D504IL

504

Backend domain `${Domain}` resolve to illegal address `${Address}`

The error message returned because the domain name resolution results are invalid at the backend.

D504CO

504

Backend service connect failed `${Reason}`

The error message returned because the backend connection failed. Check the security group configurations, the status of the backend server, and the firewall configurations.

D504CS

504

Backend http ssl connect failed `${Reason}`

The error message returned because the backend connection over HTTPS failed. Check whether the backend protocol matches the port.

D504TO

504

Backend service request timeout

The error message returned because the backend request timed out.

X504VE

504

Backend service vpc mapped failed

The error message returned because the VPC mapping at the backend is invalid. Submit a ticket to contact Alibaba Cloud technical support.

D503BB

503

Backend circuit breaker busy

The error message returned because the API is protected by its circuit breaker.

D503CB

503

Backend circuit breaker open, ${Reason}

The error message returned because the circuit breaker is open for the API. Check the backend performance of the API.

I508LD

508

Loop Detected

The error message returned because a loopback call is detected.

I404DD

404

Device id ${DeviceId} not found

The error message returned because the device ID is not found when you call APIs over WebSocket.

A403FC

403

Function Compute AssumeRole failed ${RequestId}:${Reason}

The error message returned because an authorization error has occurred when Function Compute serves as the backend service.

D502FC

502

Function Compute response invalid: ${Reason}

The error message returned because the response from the backend Function Compute service is invalid.

N502RE

502

Send Response IO Exception: ${Reason}

The error message returned because an error has occurred when the server sends a response to the client. This error message is returned often because the client closes the connection in advance or a network error has occurred.

X500ER

500

Service Internal Error

The error message returned because an internal server error has occurred. Submit a ticket to contact Alibaba Cloud technical support.

X503BZ

503

Service Busy

The error message returned because the API Gateway service is busy. Try again later or submit a ticket to contact Alibaba Cloud technical support.

X504TO

504

Service timeout

The error message returned because the API Gateway service timed out.

Specific error codes may change when the service is updated or new features are added.

2. Error codes for API Gateway instances of the classic network type

2.1. Error codes for servers

The reported HTTP status code is 5XX, which indicates that services are unavailable. In this case, we recommend that you try again later or contact the API provider.

Error code

HTTP status code

Description

Solution

Internal Error

500

The error code returned because an internal error has occurred.

Try again later.

Failed To Invoke Backend Service

500

The error code returned because the backend service failed.

Try again later. If the issue persists, contact the API provider.

Service Unavailable

503

The error code returned because the service is unavailable.

Try again later.

Async Service

504

The error code returned because the backend service timed out.

Try again later.

2.2. Error codes for clients

The reported HTTP status code is 4XX, which indicates a business error. The business error can be an invalid parameter, an invalid signature, an incorrect request method, or an error due to throttling. Carefully view error information before you troubleshoot issues.

Error code

HTTP status code

Description

Solution

Throttled by USER Flow Control

403

The error code returned because throttling for the user is triggered.

Contact the API provider to modify the value of the userDefault parameter.

Api Prov

403

The error code returned because throttling for the user is triggered.

Contact the API provider to modify the value of the userDefault parameter.

Throttled by APP Flow Control

403

The error code returned because throttling for the app is triggered.

Contact the API provider to modify the value of the appDefault parameter.

Throttled by API Flow Control

403

The error code returned because throttling for the API is triggered.

Contact the API provider to modify the value of the apiDefault parameter.

Throttled by DOMAIN Flow Control

403

The error code returned because the number of requests to the specific second-level domain name per day exceeds the upper limit or the number of requests to the specific group per second exceeds the upper limit.

You can use a system-assigned second-level domain name to make a maximum of 100 API calls per day in regions outside the Chinese mainland and a maximum of 1,000 API calls per day in regions in the Chinese mainland. The maximum queries per second (QPS) on a group is 500.

Quota Exhausted

403

The error code returned because the purchased quota has been exhausted.

Purchase a higher quota.

Expiry of Authorization

403

The error code returned because the authorization expired.

Grant the permissions again and specify the validity period based on your business requirements.

Quota Expired

403

The error code returned because the purchased quota expired.

Purchase the service again.

User Arrears

403

The error code returned because your account has overdue payments.

Top up your account.

Empty Request Body

400

The error code returned because the HTTP request body is empty.

Check the body of the request.

Invalid Request Body

400

The error code returned because the HTTP request body is invalid.

Check the body of the request.

Invalid Param Location

400

The error code returned because the location of a request parameter is invalid.

Check the location of the request parameter.

Unsupported Multipart

400

The error code returned because file upload is not supported.

The API does not support file upload.

Invalid Url

400

The error code returned because the request URL is invalid.

Check the Path, Method, and environment settings of the request.

Invalid Domain

400

The error code returned because the domain name is valid.

The API cannot be found based on the domain name. Contact the API provider.

Invalid HttpMethod

400

The error code returned because the HTTP method is valid.

Specify a valid HTTP method.

Invalid AppKey

400

The error code returned because the AppKey is invalid or does not exist.

Check the AppKey. Make sure that no extra spaces exist on the left or right side of the AppKey.

Invalid AppSecret

400

The error code returned because the AppSecret is invalid.

Check the AppSecret. Make sure that no extra spaces exist on the left or right side of the AppKey.

Timestamp Expired

400

The error code returned because the timestamp has expired.

Check whether the timestamp in the request is in the correct time zone.

Invalid Timestamp

400

The error code returned because the timestamp is invalid.

Specify a valid timestamp. For more information, see the Request signature topic.

Empty Signature

401

The error code returned because the signature is empty.

Add the calculated signature string to the request. For more information, see the Request signature topic.

Invalid Signature, Server StringToSign:%s

400

The error code returned because the signature is invalid.

Check the signature.

Invalid Content-MD5

400

The error code returned because the Content-MD5 value is invalid.

Check whether an MD5 value is specified for an empty request body or whether the MD5 value is correct if the request body is not empty.

Unauthorized

403

The error code returned because the app is not authorized to call the API.

Make sure that the app is authorized to call the API.

Nonce Used

400

The error code returned because the value of the SignatureNonce parameter has been used.

Make sure that the value of the SignatureNonce parameter is not reused.

API Not Found

400

The error code returned because the specified API cannot be found.

Check the values of parameters such as GroupId and Stage. Make sure that the API is not unpublished.

OpenID Connect Verify Fail: 243, Not found by keyId:%s

401

The error code returned because the OpenID Connect authentication failed.

1. Check whether the token that you use is generated by using the sample code in the on-premises demo. The token must be generated by calling the authorization API operation in the deployment environment. 2. Make sure that the authentication type is set to OpenID Connect for both the authorization API operation and business API operation. 3.Make sure that the key ID and public key that you specify to call the authorization API operation are the same as those used by the backend service.

3. Error codes for management and control API operations

When you call API operations provided by API Gateway, such as CreateAPI, ModifyAPI, or DeleteAPI, error codes that are listed in the following tables may be reported.

3.1.Error codes for servers

The reported HTTP status code is 5XX, which indicates that services are unavailable. In this case, we recommend that you try again later.

Error code

Error message

HTTP status code

Description

Solution

ServiceUnavailable

The request has failed due to a temporary failure of the server.

503

The error message returned because the service is unavailable.

Try again later.

InternalError

The request processing has failed due to some unknown error, exception or failure.

500

The error message returned because an internal error has occurred.

Try again later.

3.2. Error codes for clients

The reported HTTP status code is 4XX, which indicates a business error. The business error can be a parameter error, an error due to access control, or a business logic error. Carefully view error information before you troubleshoot issues.

Error code

Error message

HTTP status code

Description

Solution

Repeated%s

The specified %s is repeated.

400

The error message returned because the value of the %s parameter has been used.

Modify the parameter and try again.

RepeatedCommit

Resubmit request.

400

The error message returned because the request has been submitted.

Do not repeatedly submit the same request.

Missing%s

The %s is mandatory for this action.

400

The error message returned because the %s parameter is not specified.

Specify the %s parameter based on the error description and try again.

MissingAppIdOrAppOwner

AppId or AppOwner must have a valid value.

400

The error message returned because the AppId or AppOwner parameter is not specified.

Specify the AppId or AppOwner parameter, or both of them.

Invalid%s

The specified parameter %s value is not valid.

400

The error message returned because the specified parameter is invalid.

View the requirements on the specified parameter, modify the parameter, and then try again.

NotFound%s

Cannot find resource according to your specified %s.

400

The error message returned because no resources can be found based on the value of the %s parameter.

Check whether the %s parameter is correctly specified.

InvalidFormat%s

The specified parameter %s value is not well formatted.

400

The error message returned because the parameter format is invalid.

View the requirements on the format of the parameter value, modify the parameter value, and then try again.

Duplicate%s

The specified parameter %s value is duplicate.

400

The error message returned because the value of the %s parameter has been used.

Change the parameter value and try again.

DependencyViolation%s

The specified %s has %s definitions.

400

The error message returned because the parameter dependency is invalid.

Remove the dependency. A parameter on which other parameters depend cannot be deleted. To delete such a parameter, remove the dependencies first.

Forbidden%s

Not allowed to operate on the specified %s.

403

The error message returned because you are not allowed to perform the specified operation.

Obtain the permission to perform the specified operation.

NoPermission

User is not authorized to operate on the specified resource.

403

The error message returned because you are not authorized to perform operations on the specified resource.

Obtain the permissions to perform operations on the specified resource.

ExceedLimit%s

The specified %s count exceeds the limit.

400

The error message returned because the number of APIs, API groups, or applications created within your Alibaba Cloud account exceeds the quota.

Adjust the quota of APIs, API groups, or applications.

UserNotFound

The specified user can not be found.

404

The error message returned because the specified user does not exist.

Enter valid information about the user.

DomainCertificateNotFound

Cannot find the domain certificate.

400

The error message returned because the certificate for the specified domain name does not exist.

Check the ID and name of the uploaded certificate.

DomainNotResolved

The specified domain has not been resolved.

400

The error message returned because the specified domain name cannot be resolved.

Bind a specific CNAME record to the second-level domain name of the group. Domain name resolution is performed by the domain name registrar from which you purchase the domain name.

InvalidICPLicense

The specified domain have not got ICP license, or the ICP license does not belong to Aliyun.

400

The error message returned because the Internet Content Provider (ICP) filing for the specified domain name is invalid.

Apply for an ICP filing for the domain name in Alibaba Cloud ICP Filing System. If you have applied for an ICP filing for the domain name in other systems, you must add Alibaba Cloud as a service provider to the ICP filing. To apply for an ICP filing, you must obtain a service identification number. Each Alibaba Cloud Elastic Compute Service (ECS) instance with a public IP address provides five service identification numbers.

Invalid%s.LengthLimit

The parameter %s length exceeds the limit.

400

The error message returned because the value of the %s parameter exceeds the upper limit in length.

Change the parameter value and try again.

InvalidApiDefault

The ApiDefault value exceeds limit.

400

The error message returned because the value of the apiDefault parameter exceeds the threshold.

Change the value of the apiDefault parameter. The value of the apiDefault parameter cannot exceed 100 million, regardless of the unit. To adjust the maximum value of the apiDefault parameter, submit a ticket.

InvalidAppDefault

The AppDefault value must smaller than the UserDefault and ApiDefault.

400

The error message returned because the value of the appDefault parameter does not meet requirements.

Change the value of the appDefault parameter. The value must be less than that of the apiDefault parameter and also less than that of the userDefault parameter.

InvalidUserDefault

The UserDefault value must bigger than the AppDefault and smaller than the ApiDefault.

400

The error message returned because the value of the userDefault parameter does not meet requirements.

Change the value of the userDefault parameter. The value must be greater than that of the appDefault parameter but less than that of the apiDefault parameter.

InvalidParamMapping

Parameters must be fully mapped.

400

The error message returned because the parameter mapping is invalid.

Specify a backend parameter for each request parameter. When you create an API, map each request parameter to a backend parameter.

InvalidOwnerAccount

OwnerAccount is invalid.

400

The error message returned because the account of the application owner is invalid.

The Alibaba Cloud Mail address is used. However, this account is invalid. Change the account of the application owner and try again.

ServiceForbidden

Your Gateway service is forbidden by risk control.

400

The error message returned because the API Gateway service is denied by the risk control system.

Do not send a large number of requests in a short time. Try again later. If the issue persists, submit a ticket.

ServiceUnOpen

Your Gateway service has not been opened.

400

The error message returned because API Gateway is not activated.

Activate API Gateway on the Alibaba Cloud International site.

ServiceInDept

Your API Gateway service is in dept.

400

The error message returned because the API Gateway service has overdue payments.

Top up your account or settle the overdue payments.

EqualSignature

The new signature is the same as the old.

400

The error message returned because the new backend signature key is the same as the previous one.

Modify the new backend signature key. Make sure that the newly configured key-secret pair is different from the previous one.

CertificateNotMatch

The domain does not match the one in the certificate.

400

The error message returned because the specified domain name does not match the domain name in the certificate.

Make sure that the specified domain name matches the domain name in the certificate.

CertificateKeyNotMatch

The certificate private key does not match the public key.

400

The error message returned because the public and private keys in the certificate do not match.

Check the certificate and make sure that the public and private keys in the certificate match.

PrivateKeyEncrypted

The certificate private key is encrypted, please upload the unencrypted version.

400

The error message returned because the private key of the certificate is encrypted.

Specify a private key that is not encrypted.

CertificateSecretKeyError

The certificate private key is invalid.

400

The error message returned because the private key of the certificate is invalid.

Specify a correct private key.

InvalidApiServiceAddress

The specified service address is not valid.

400

The error message returned because the specified IP address of the backend service is invalid.

Modify the configurations of the backend service.

3.3. Common error codes for clients

The reported HTTP status code is 4XX, which indicates a business error and may be reported when you call APIs of Alibaba Cloud services. The business error can be an invalid request format, an incorrect request method, missing required parameters, an invalid parameter value format, an invalid signature, or an error due to throttling. Carefully view error information before you troubleshoot issues.

Scenario

Error code

Error message

Status code

Suggestion

The specified API cannot be found.

InvalidApi.NotFound

Specified api is not found, please check your url and method.

404

Check whether the specified API operation name is valid. The name is case-sensitive.

A required parameter is not specified.

Missing{ParameterName}

{ParameterName} is mandatory for this action.

400

Specify the required parameter.

The AccessKey ID cannot be found.

InvalidAccessKeyId.NotFound

Specified access key is not found.

404

Check whether a valid AccessKey ID is used when you call the API.

The AccessKey ID is disabled.

InvalidAccessKeyId.Inactive

Specified access key is disabled.

400

Check whether the AccessKey pair is available.

The format of the date or timestamp is invalid.

InvalidTimeStamp.Format

Specified time stamp or date value is not well formatted.

400

Check the timestamp.

The difference between the client time and server time exceeds 15 minutes.

InvalidTimeStamp.Expired

Specified time stamp or date value is expired.

400

Check the timestamp.

The SignatureNonce value has been used.

SignatureNonceUsed

Specified signature nonce was used already.

400

The returned parameter value is in an invalid format.

InvalidParameter.Format

Specified parameter format is not valid.

400

Specify the parameter only in the XML or JSON format.

The parameter value verification fails.

Invalid{ParameterName}

Specified parameter {ParameterName} is not valid.

400

Check the parameter value.

The HTTP request method is not supported.

UnsupportedHTTPMethod

Specified signature is not matched with our calculation.

400

Check the request method.

The signature method is not supported.

InvalidSignatureMethod

Specified signature method is not valid.

400

Specify an available signature method. This parameter can be left empty.

The signature verification fails.

SignatureDoesNotMatch

Specified signature is not matched with our calculation.

400

Check the signature.

The user-level call frequency exceeds the threshold.

Throttling.User

Request was denied due to user flow control.

400

Reduce the call frequency.

The API-level call frequency exceeds the threshold.

Throttling.API

Request was denied due to api flow control.

400

Reduce the call frequency.

The AccessKey ID is missing.

MissingSecurityToken

SecurityToken is mandatory for this action.

400

Check whether you specify a valid AccessKey ID.