Error Codes

When a GStable API request fails, even if the HTTP status code returns 200 OK, the code field in the response body will contain a non-zero error code.

This page lists all predefined business error codes to help you handle exceptions programmatically.

Error Response Structure

As described in the Introduction, you need to check the code in the JSON response.

{
  "code": 100203,
  "message": "Session is expired",
  "data": null
}

Dynamic Error Messages

The message field is usually a fixed error description, but in some validation errors, it may contain specific context information in the format Error Description: Specific Info.

For example:

• Standard Message: "Invalid field format"
• Detailed Message: "Invalid field format: email is required"

Best Practice

Do not write business logic by parsing the message string, as the text may be adjusted. Always use the code (error code) for program flow control.

---

1. Payment Flow Errors (Payment Flow)

Business logic errors involving Payment Links, Checkout Sessions, and Products.

Payment Link (1001XX)

Code	Message	Description & Cause
100101	Payment link not found	The specified Payment Link ID does not exist.
100102	Payment link is archived	The payment link has been archived and cannot be accessed or modified again.
100103	Payment link is not active	The payment link has been disabled.
100104	Invalid payment link version	The requested link version is not supported.

Checkout Session (1002XX)

Code	Message	Description & Cause
100201	Session not found	The specified Checkout Session ID does not exist.
100202	Session client key is invalid	The provided Client Key failed validation.
100203	Session is expired	The session has expired (default 30 minutes) and payment cannot proceed.
100204	Session is paid	The session has already been paid and cannot be paid again.
100205	Session is cancelled	The user or merchant actively cancelled the session.
100206	Session payer mismatch	The actual payer does not match the session's preset payer information.
100207	Receipt not found	The transaction receipt for the session could not be found.
100208	Payment session is not completed	Attempted to query results while the session payment is not yet completed.
100209	Onchain transaction not found	The associated transaction hash could not be traced on the blockchain.
100210	Session lock failed	The session is currently locked by another process. Please retry later.
100211	Session is not cancellable	The session cannot be cancelled in its current state.

Product Management (1003XX)

Code	Message	Description & Cause
100301	Product not found	The specified Product ID does not exist.
100302	Product partial missing	Some product IDs in a batch operation do not exist.
100303	Product partially unavailable	Some products in a batch operation are unavailable.
100304	Product is not active	The product is not active and cannot be used to create links or sessions.
100305	Product has been used	The product has been linked/used and certain modifications cannot be performed.
100306	Product has been removed	The product has been logically deleted.

---

2. Integration & Configuration Errors (Integration)

Errors involving API Key authentication and Webhook configuration.

API Key (2001XX)

Code	Message	Description & Cause
200101	API key not found	Key not provided in Request Header or Key does not exist.
200102	API key is rotating	The Key is currently rotating and temporarily unavailable.
200103	API key is revoked	The Key has been revoked, please generate a new Key.
200104	Invalid expired time	The expiration time setting for the Key is invalid.
200105	API key limit reached	The number of API Keys generated for the account has reached the limit.
200106	API key is not active	The API Key is not in an active state.

Webhook (2002XX)

Code	Message	Description & Cause
200201	Webhook not found	The specified Webhook ID does not exist.
200202	Failed to ping webhook	Failed to test send Webhook, please check if the target URL is reachable.
200203	Webhook limit reached	The number of Webhook Endpoints has reached the limit.

---

3. User & Account Errors (User & Account)

Errors involving merchant login, account status, and report queries.

Authentication & Status (3001XX - 3002XX)

Code	Message	Description & Cause
300101	Invalid sign in	Invalid login credentials.
300102	Authentication check failed	Two-factor authentication or security check failed.
300201	User not found	User does not exist.
300202	User is blocked	User has been blocked and cannot perform operations.

Account Configuration (3003XX)

Code	Message	Description & Cause
300301	Account is not found	Merchant account does not exist.
300302	Account is removed	Merchant account has been removed.
300303	Account address already exists	The collection address attempted to be added already exists.
300304	Unsupported settlement token of the account	The account does not support this settlement token configuration.
300305	Account count limit reached	The number of accounts has reached the system limit.
300306	At least one account is required	Operation failed because at least one account must remain.

Report Query (3004XX)

Code	Message	Description & Cause
300401	Report not found	The requested report does not exist.
300402	Report is duplicated	Duplicate creation of the same report task.
300403	Report has no data in the time range	No data available to generate report within the specified time range.
300404	Report data count is too large	The amount of requested data is too large, please shorten the query time range.

---

4. Common & Validation Errors (Common)

Request parameter format validation and unsupported channel errors.

Code	Message	Description & Cause
400101	Invalid field format	Parameter format error (e.g., illegal email, URL, or number).
400201	Unsupported currency	The requested currency is not in the GStable supported list.
400202	Unsupported channel	The requested blockchain channel or network is not supported.
400203	Settlement capabilities not found	The system could not find valid settlement capabilities for this configuration.
400301	Stat not found	The requested statistical data does not exist.

---

5. Platform System Errors (Platform)

Errors involving system rate limiting, database, and internal exceptions.

Code	Message	Description & Cause
900101	Too many requests	Request frequency exceeded quota (QPS limit). Suggest implementing backoff retry.
900201	Failed to create record	Database write failed.
900202	Failed to update record	Database update failed.
900203	Failed to query record	Database query failed.
900301	Image processing failed	Image upload or processing failed.
999999	Internal system error	Unknown internal system error. Please contact the GStable support team and provide the Trace ID.