Error Handling

The API uses a consistent error response format across all endpoints.

Error Response Format

All errors follow this structure:

{
  "errorCode": 2001,
  "errorLabel": "UNSUPPORTED_TICKER",
  "errorDescription": "Ticker XYZ is not supported",
  "errors": {
    "ticker": ["Unsupported ticker value"]
  }
}

Field	Type	Description
`errorCode`	number	Numeric error code (see table below)
`errorLabel`	string	Machine-readable error label
`errorDescription`	string	Human-readable error description
`errors`	object	(optional) Field-level validation errors. Keys are field names, values are arrays of error messages.

Error Codes

Validation Errors (1xxx)

Code	Label	Description
1001	`INVALID_TIMESTAMP`	The provided timestamp is invalid or expired
1002	`BAD_RECV_WINDOW`	The receive window parameter is out of range

Business Logic Errors (2xxx)

Code	Label	Description
2001	`UNSUPPORTED_TICKER`	The specified ticker is not supported
2002	`AMOUNT_TOO_SMALL`	The amount is below the minimum threshold
2003	`INVALID_SIDE`	Invalid conversion side parameter
2004	`INSUFFICIENT_FUNDS`	Insufficient balance to complete the operation
2005	`PAIR_NOT_SUPPORTED`	The trading pair is not available
2006	`INVALID_UUID`	The provided UUID is malformed
2007	`CONVERT_WRONG_STATUS`	The conversion is in a state that does not allow this action
2008	`RATE_NOT_FOUND`	No rate available for the requested pair
2009	`PRODUCT_NOT_AVAILABLE`	The requested product is not available for this account

Service Errors (3xxx)

Code	Label	Description
3001	`CONVERT_ERROR`	Internal error in the conversion service
3101	`WALLET_ERROR`	Internal error in the wallet service

System Errors (9xxx)

Code	Label	Description
9001	`UNAUTHORIZED`	Authentication failed
9002	`FORBIDDEN`	Access denied
9003	`SERVICE_UNAVAILABLE`	A backend service is temporarily unavailable
9004	`TOO_MANY_REQUESTS`	Rate limit exceeded
9005	`INTERNAL_SERVER_ERROR`	Unexpected server error
9006	`MISSING_API_KEY`	The `x-apikey` header is missing
9007	`INVALID_API_KEY`	The API key is invalid or revoked
9008	`MISSING_SIGNATURE`	Request signature is missing
9009	`INVALID_SIGNATURE`	Request signature is invalid
9012	`INVALID_IP`	Request IP address is not in the API key's allowlist
9010	`NOT_FOUND`	The requested resource was not found
9011	`BAD_REQUEST`	The request is malformed or contains invalid parameters
9013	`KYC_NOT_VERIFIED`	KYC verification not completed
9014	`API_NOT_AVAILABLE`	API access is not available for this account

HTTP Status Codes

HTTP Status	Meaning
200	Success
400	Bad Request — validation or business logic error
401	Unauthorized — authentication failure
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded
500	Internal Server Error
503	Service Unavailable — backend service is down