Error code reference

Response structure

Standard APIs return:

{
  "code": 40013,
  "msg": "Signature verification failed. Please check the authentication parameters.",
  "data": null
}

Field	Description
code	Business code. 200 on success; on failure, one of the error codes below
msg	Error description that can be shown directly to the caller
data	Business data on success; usually null on failure

HTTP status and business codes

Most gateway business errors (authentication failure, no permission, IP blocking, WAF blocking) return HTTP 200; you need to read code to determine the result. Exceptions: authentication/authorization failures for authType=jwt return 401/403/503; flow control returns 429, circuit breaking returns 503, downstream unavailable returns 503, and timeout returns 504.

The code output by the gateway's top-level exception handler is a string (such as "50001"), while filters and business APIs usually output numeric values. Clients should handle both strings and numbers when parsing.

Authentication and authorization (40001–40033)

Error code	Message	Common causes	Troubleshooting advice
40001	API not found or offline	Path/method mismatch, API not released, route not synced	Verify the release environment and path prefix; check the gateway routes
40002	Authentication failed: the app has no permission for the API	The API is not authorized to the app	Grant authorization in app authorization or approval
40003	The API authorization has expired	The authorization is time-limited and has expired	Renew it or switch to permanent authorization
40006	The API is offline	The release snapshot was taken offline	Bring it online again and sync the environment
40007	The API call count has reached the limit	Authorization/subscription quota exhausted	Adjust the quota or retry the next day
40008	X-AppKey in the header cannot be empty	Simple authentication without an AppKey	Add X-AppKey
40009	Authentication parameters cannot be empty	Signature authentication missing AppKey/Timestamp/Sign	Provide all four authentication headers
40010	Timestamp expired / nonce invalid	Time skew over 10 minutes, or nonce replay	Calibrate the clock; generate a new nonce for each request
40012	The IP address is not in the valid range	API-level IP rule blocked	Check the rule type (allow/deny list) and the client egress IP
40013	Signature verification failed	Wrong AppSecret, incorrect sign string construction, algorithm mismatch	Check each item against the signature guide
40018	The IP address is not in the authentication authorization range	App credential-level IP whitelist blocked	Add the egress IP in the app configuration
40019	App disabled	The app has been disabled	Enable the app
40020	MCP is not enabled for this app	Accessing /mcp/{appCode} but MCP is not enabled for the app	Enable MCP in the app settings
40021	Subscription expired or frozen	Subscription expired, unsubscribed, or frozen	Check the subscription status and validity period
40022	The target address is not allowed	Proxy mode target hit the outbound blacklist	Adjust the target address or security policy
40023	Subscription daily call quota exceeded	Subscription daily quota exhausted	Retry the next day or adjust the quota
40024	Authorization header must not be empty	An oauth2 API call has no Authorization: Bearer <token>, or the Bearer prefix is misspelled	Exchange a token at /oauth2/token first, then add the header
40025	Token invalid or expired	Token expired, tampered with, issued by another environment, or the app was deleted	Exchange a new token and verify the environment the token came from
40026	Token revoked, please obtain a new one	The token was revoked (server-side session deleted)	Exchange a new token
40028	Authorization header is missing the Bearer token	A JWT API call has no Authorization header, or the value is empty	Add Authorization: Bearer <token>
40029	JWT invalid or expired	Invalid signature, iss, aud, exp, typ, kid, or claims; malformed Authorization header	Check each requirement in Enterprise IdP JWT authentication
40030	Identity provider temporarily unavailable, please retry later	JWT is disabled, or the IdP / JWKS is unreachable	Check apigo.jwt.enabled and IdP connectivity; retry after Retry-After
40031	JWT subject is not bound to any app	The token subject does not match the credential binding	Configure JWT identity binding on the credential and confirm the subject matches exactly
40032	Insufficient JWT scope	The scope requirement is not met (reserved)	Check the scopes issued by the IdP
40033	This app is bound to an enterprise identity; static credentials are disabled	An app bound to JWT still calls with X-AppKey / appSecret while the switch is on	Use the Bearer token issued by the IdP, or turn off apigo.jwt.disable-static-credentials-for-bound-apps

The /oauth2/token endpoint does not use the codes above; it returns OAuth2 standard errors (invalid_request / unsupported_grant_type / invalid_client / server_error). See OAuth2 client credentials authentication.

JWT authentication (authType=jwt) uses standard HTTP semantics: 401 (missing/invalid token), 403 (subject unbound/app disabled/IP/not authorized), and 503 (IdP unavailable). The body still uses {code,msg} and may additionally include error / error_description and WWW-Authenticate. API-not-found and API-offline are evaluated before authentication and still return HTTP 200. See Enterprise IdP JWT authentication.

401/402 semantics: 401 means the login session has expired, and 402 means the user is not logged in. Both apply to admin JWT sessions and do not appear in the open API signature flow.

Parameters and SQL (41000–41013)

Error code	Message	Description
41000	Required parameter cannot be empty	A required parameter defined by the API is missing
41006	The API path is already in use	Path + method conflict on save (the admin also returns 50011)
41007	At least one of the multi-select parameters must be provided	Parameter validation rule not satisfied
41008	Invalid request parameter value format	Type conversion failed, e.g. text passed for a numeric parameter
41009	Only one of the mutually exclusive parameters may be provided	Mutually exclusive parameters provided together
41010	Pagination parameters cannot be empty	Pagination API missing the page number or page size
41011	Invalid request parameter name	The parameter name uses a runtime reserved word
41012	Invalid SQL interpolation parameter	Unsafe ${} interpolation used; change to #{} prepared statements
41013	Orchestration rule validation failed	Invalid field orchestration configuration in LAYOUT mode
40011	SQL execution failed	SQL syntax error, missing table/field, data source connection error
40014	SQL contains special characters	Characters such as - not wrapped in double quotes
40015	Operation type not supported	The current mode does not support the operation (e.g. a non-query SQL going through the cache)
40016	Third-party API call failed	The proxy target returned an error or the connection failed

System and data sources (5xxxx)

Error code	Message	Description
50001	System busy	Unified fallback for uncaught exceptions
50002	System upgrading	Service maintenance state
50003	Downstream service instance connection error	Execution service unreachable
50004	API response timeout	Downstream processing timeout
50010	Login failed, please check the database connection	Querying the user failed during login
50011	The API path already exists	Path conflict when saving the API
51001	Data source initialization failed	Connection pool creation failed
51002	Failed to query the schema / index list	Data source configuration or permission issue
51003	Plugin name cannot be empty	Driver getName() returned empty
51004	Plugin name already exists	Two drivers registered the same type name
51005	Failed to query indexes	Metadata read failed
52005	Missing request parameters	Missing required parameters during SQL construction
55000	Plugin exception	Internal error in the data source driver
44001	Null pointer exception	Null pointer in the gateway processing chain; check the logs
45001	Database password decryption failed	The data source password ciphertext does not match the key

Permissions and operations (43xxx)

Error code	Message	Description
43000	Invalid operation	The operation is not allowed in the current state
43001	Invalid API	The API does not exist or has been deleted
43002	API already released, take it offline first	Released APIs cannot be edited directly
43003	No operation permission	The current user has no permission on the project/resource

MCP protocol errors

The MCP endpoint returns JSON-RPC 2.0 error objects and does not use the {code,msg,data} structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Error code	Meaning	Scenario
-32600	Invalid Request	The request body is not valid JSON-RPC, or the method name is missing
-32601	Method Not Found	Called an unimplemented method
-32602	Invalid Params	Missing parameters, type errors, tool not authorized
-32603	Internal Error	Tool execution failed, insufficient permission, response body too large, gateway internal error

When an MCP request is rate limited or circuit-broken, the HTTP status is 429 or 503 respectively, and the response body remains a JSON-RPC error object.

License errors (L001–L015)

License validation failures block service startup or trigger an exit. For error codes, see Deployment topology and License.

Troubleshooting order

1. Check the HTTP status first: for 429 check flow control rules, for 503 check circuit breaking and instance health, for 504 check the timeout configuration.
2. Then check the business code: for authentication errors (400xx), verify AppKey/signature/IP first; for parameter errors (410xx), verify the input parameters and types.
3. Use the traceId: the X-TraceId response header can be used to locate the full request chain in the call logs.
4. Confirm the release state: 40001 and 40006 are usually caused by an unsynced environment or an API that is not online.
5. Check runtime sync: if rule or route changes do not take effect, run a manual reconciliation.

Related documents

• Signature authentication guide
• OAuth2 client credentials authentication
• Enterprise IdP JWT authentication
• Flow control and circuit breaking
• IP access control and WAF
• MCP access