Error Handling

All API errors follow a consistent format. Use the error code for programmatic handling and the message for debugging.

Error Format

Every error response contains an error object with a machine-readable code, a human-readable message, and an optional details object with field-level information.

422Validation error example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "amount": "Must be at least 32000"
    }
  }
}

Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Missing or invalid API key / JWT
FORBIDDEN	403	Key lacks the required permission
NOT_FOUND	404	Resource does not exist
DUPLICATE_REQUEST	409	Idempotency key already used with different parameters
VALIDATION_ERROR	422	Request body failed validation
INSUFFICIENT_BALANCE	422	Account balance too low for the operation
BELOW_MINIMUM_ORDER	422	Order amount is below provider minimum
INVALID_ADDRESS	422	TRON address failed validation
PRICE_EXCEEDED	422	Current price exceeds the specified max price
RATE_LIMITED	429	Too many requests, check Retry-After header
PROVIDER_UNAVAILABLE	503	No providers can fulfill the request
MAINTENANCE	503	Platform is undergoing maintenance
INTERNAL_ERROR	500	Unexpected server error

Retry Strategy

Not all errors should be retried. Use the HTTP status and error code to decide how to handle each case.

4xx errors - do not retry. Fix the request first.
429 - retry after the delay specified in the Retry-After header.
503 - retry with exponential backoff (1s, 2s, 4s, up to 30s).
500 - retry with exponential backoff. If persistent, contact support.

Idempotency

The POST /orders and POST /withdraw endpoints support the Idempotency-Key header. Sending the same key with identical parameters returns the original response without creating a duplicate.

409Duplicate request with different parameters

{
  "error": {
    "code": "DUPLICATE_REQUEST",
    "message": "Idempotency key already used with different parameters"
  }
}

IDEMPOTENCY KEYS

Use a UUID v4 or a deterministic hash of the request parameters. Keys are valid for 24 hours. Always include an idempotency key on order and withdrawal requests to prevent accidental duplicates.