All Products
Search
Document Center

API Gateway:Error codes

Last Updated:Jan 05, 2024

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 to shared instances of the virtual private cloud (VPC) type and dedicated instances of the VPC type.

  • If the X-Ca-Error-Code header is not empty in a response received by a client, the error code is generated by API Gateway. Such an error code is a six-character string. The following table lists all possible error codes that may be generated by API Gateway. For the detailed error message, refer to the X-Ca-Error-Message header.

  • 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 the HTTP request header is invalid.

I400MH

400

Header `${HeaderName}` is Required

The error message returned because the 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 configuration. Check the API configuration.

I413RL

413

Request body too Large

The error message returned because the request body is too large. For more information, see Limits.

I413UL

413

Request URL too Large

The error message returned because the request URL is too long. For more information, see Limits.

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 an unknown domain name is requested. Use a bound domain name for the call.

I410GG

410

Group's instance invalid

The error message returned because an invalid instance is requested. The API group may not belong to the current 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 could not be found in the current environment based on the path and method parameters in the request. For more information, see What do I do if the I404NF error is reported?

X400PM

400

Invalid plugin meta ${PluginName} ${Reason}

The error message returned because the metadata of the plug-in is invalid.

X500ED

500

Expired api definition

The error message returned because expired metadata of earlier versions is no longer supported by the new version of API Gateway. To modify the metadata of an earlier version, submit a ticket.

X500AM

500

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

The error message returned because the format of the saved metadata is invalid. To fix this issue, submit a ticket.

X403DG

403

Bad Domain or Group: ${Reason}

The error message returned because the data of the API group is invalid.

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 API 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 an overdue payment. If the API is purchased in Alibaba Cloud Marketplace, contact the service provider.

A401AC

401

Invalid AppCode ${Reason}

The error message returned because AppCode authentication is used but the AppCode is not found. Check whether the application is authorized and whether the AppCode is correct.

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 Invalid signature.

A403EP

403

App authorization expired

The error message returned because the authorization expired. Grant permissions again.

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 provided in the X-Ca-Timestamp header has expired. The timestamp is valid for 15 minutes

I400MP

400

Parameter `${ParameterName}` is required

The error message returned because one or more required parameter in the API configuration are left empty.

I400IP

400

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

The error message returned because the value of a parameter in the API configuration is invalid.

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 resolved.

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 the limit of API calls is exceeded. If you use the default second-level domain name, the limit is 1,000 calls per day for regions in the Chinese mainland and 100 calls per day for regions outside the Chinese mainland.

T429IN

429

Throttled by INSTANCE Flow Control

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

T429GR

429

Throttled by GROUP Flow Control

The error message returned because throttling is triggered for the current API group. Upgrade the instance specification.

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}

APIs and API groups cannot be called over the Internet. You can call them over a private network. For more information, see VPC-based API Calls.

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 request path and the request method that are 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 an overdue payment. Contact the service provider.

B403MQ

403

Api Market Subscription quota exhausted

The error message returned because the quota of Alibaba Cloud Marketplace-purchased APIs has been exhausted. Renew the quota.

B403ME

403

Api Market Subscription expired

The error message returned because the API subscription has expired. Create another subscription.

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 backend domain name fails to be resolved. Verify the backend domain name.

D504IL

504

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

The error message returned because the resolution result for the domain name of the backend service is invalid.

D504CO

504

Backend service connect failed `${Reason}`

The error message returned because API Gateway failed to access the backend service. In this case, you must check the security group and firewall settings or the status of the backend server. For more information, see Troubleshoot D504CO errors.

504

Backend service connect failed `Connection lease request time out`

The error message returned because the backend service fails to be connected due to dry connection pool. Upgrade the instance specification.

D504CS

504

Backend http ssl connect failed `${Reason}`

The error message returned because the backend service fails to be connected over HTTPS. Check whether the protocol that is configured for the backend service matches the port.

D504TO

504

Backend service request timeout

The error message returned because the request to the backend service times out. Increase the backend timeout period or improve the handling capability of the backend service.

X504VE

504

Backend service vpc mapped failed

The error message returned because the VPC mapping of the backend service fails.

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 performance of the backend service.

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 occurred when Function Compute is used as the backend service.

D502FC

502

Function Compute response invalid: ${Reason}

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

N502RE

502

Send Response IO Exception: ${Reason}

The error message returned because an exception occurred when the server sends a response to the client. Check whether the client closes the connection in advance or a network error occurred.

X500ER

500

Service Internal Error

The error message returned because an error occurred on the internal server. To fix this issue, submit a ticket to contact API Gateway technical support.

X503BZ

503

Service Busy

The error message returned because the API Gateway service is busy. Try again later.

X504TO

504

Service timeout

The error message returned because a timeout error occurs in API Gateway. To contact technical support, submit a ticket.

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

2. Error codes for API operation management

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

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.

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 code returned because an internal error occurs.

Try again later.

2.2 Error codes for clients

The reported HTTP status code is 4XX, which indicates a business error. A business error can be a parameter error, an error caused by 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 a parameter has been used. %s in the message is a placeholder that indicates a parameter name.

Change the parameter value 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 resource 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 value of the %s parameter, 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 dependency first.

Forbidden%s

Not allowed to operate on the specified %s.

403

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

Obtain the permission to perform the 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 apps created within your Alibaba Cloud account exceeds the quota.

Modify the quota of APIs, API groups, or apps.

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 is not resolved.

Bind a specific CNAME record to the second-level domain name of the API 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.

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 the value of the apiDefault parameter and 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 the value of the appDefault parameter but less than the value 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 app owner is invalid.

An invalid user ID of an Alibaba Cloud account is used when you perform authorization. Change the account of the app 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.

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 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 valid 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.

2.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

HTTP status code

Solution

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 failed.

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 failed.

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 specified a valid AccessKey ID.