Get Countries

GET/web/v1/system/constants/countries None

Description

Returns a list of all supported countries with ISO standard codes and phone codes. The response is localized based on the Accept-Language request header. This endpoint returns approximately 180+ countries and the response is cached for 24 hours due to its large payload size (50-80KB). The UNKNOWN value is excluded from the results.

Request Headers

The following headers must be provided by the caller (frontend / SDK). Other gateway headers (Cloudflare edge, Nginx reverse proxy) are injected automatically by infrastructure and are documented in Required Headers.

Header	Required	Description
X-Workspace-Id	OPTIONAL	Workspace context for workspace-scoped APIs.
X-Client-Hash	YES	Device fingerprint hash (browser: FingerprintJS visitorId).
X-LOCALE	YES	Application locale (e.g., en-US, zh-Hans).
User-Agent	YES	Client user-agent.
Accept-Language	YES	Language preference per RFC 7231.
X-Request-Id	YES	Per-request correlation (UUID v4). Frontend SHOULD provide; Nginx auto-generates if absent.

Request Parameters

None — this endpoint accepts no request body or query parameters.

Success Response

Success 200

{
  "version": "2.0.0",
  "timestamp": 1775552585763,
  "success": true,
  "code": "2000",
  "message": "Success",
  "data": [
    {
      "code": "CN",
      "value": 95010301,
      "label": "China",
      "alpha2Code": "CN",
      "alpha3Code": "CHN",
      "numericCode": 156,
      "phoneCode": "86"
    },
    {
      "code": "JP",
      "value": 95010302,
      "label": "Japan",
      "alpha2Code": "JP",
      "alpha3Code": "JPN",
      "numericCode": 392,
      "phoneCode": "81"
    }
  ]
}

Response Fields

Field	Type	Example
code	string	"CN"
value	integer	95010301
label	string	"China"
alpha2Code	string	"CN"
alpha3Code	string	"CHN"
numericCode	integer	156
phoneCode	string	"86"

Error Responses

All error responses follow the standard envelope format:

{
  "version": "2.0.0",
  "timestamp": 1775551826706,
  "success": false,
  "code": "DOMAIN.ERROR_CODE",
  "message": "Human-readable error description",
  "data": null
}

Common HTTP status codes:

Status	Meaning
400	Request validation failed (missing field, wrong type, invalid format)
401	Authentication required or token expired
403	Gateway denied the request (portal access code, IP block, MFA required, etc.)
404	Resource not found
429	Rate limit exceeded
500	Unexpected server error