Skip to main content
API request format, response structure, and error handling.

​
Quick Start

  1. Use JSON for request and response bodies with Content-Type: application/json.
  2. Authenticate as required by the API (e.g. sign, or JWT for Issuing endpoints).
  3. Handle responses using the numeric code and msg fields.

​
Request Format

​
Content Type

  • Content-Type: application/json
  • Request bodies must be valid JSON. Responses are JSON.

​
Headers

HeaderRequiredDescription
Content-TypeYesapplication/json
AuthorizationWhen requiredBearer token (e.g. JWT for Issuing) or as specified per endpoint
Some Issuing endpoints may support an Idempotency-Key header for POST requests. See the endpoint documentation.

​
Example Request

curl -X POST https://<BASE_URL>/v1/accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT>" \
  -d '{"name": "My Account", "currency": "USD"}'

​
Response Format

​
Response Body

All responses use the same structure:
  • code – Numeric result or error code (e.g. 200 for success).
  • msg – Human-readable message (may be localized).
  • data – Response payload on success; often null on error.
Success example: 
{
  "code": 200,
  "msg": "success",
  "data": { ... }
}
Error example: 
{
  "code": 559,
  "msg": "sign error!",
  "data": null
}
Use the numeric code for programmatic handling. The full list of codes is in Response Codes.

​
Response Headers

HeaderDescription
x-request-idRequest identifier; include when contacting support
Content-Typeapplication/json
Retry-AfterPresent on 429; wait time in seconds

​
HTTP Status Codes

CodeMeaningAction
200SuccessProcess response data
201CreatedProcess response data
400Bad requestFix request and retry
401UnauthorizedCheck credentials/signature
403ForbiddenCheck permissions
404Not foundVerify resource ID
409ConflictResolve conflict before retry
429Rate limitedWait and retry (see Retry-After)
500Server errorRetry with backoff
502/503/504UnavailableRetry after delay

​
Error Handling

  1. Check HTTP status first; treat 4xx and 5xx appropriately.
  2. Use the numeric code in the body for logic; see Response Codes.
  3. Log x-request-id when present for support and debugging.
  4. Retry only on 5xx or 429; fix 4xx requests before retrying.
  5. Respect Retry-After on 429.