Error Format

All error responses use a single unified format with string slug codes:

{
    "code": "ERROR_SLUG",
    "message": "Human-readable description",
    "fields": {"field_name": "error detail"}  // only for validation errors
}

The fields property is only present when code is VALIDATION_ERROR.

Error Response Tiers

HTTP Status	Code	When
400	`BAD_REQUEST`	Invalid input caught by handler (pair not found, invalid format, negative amounts, disabled order type)
400	`MALFORMED_JSON`	Request body is not valid JSON
400	Business slug (see table below)	Business logic error from trading core
401	`UNAUTHORIZED`	Missing or invalid auth
403	`FORBIDDEN`	Missing signature, insufficient permissions, pair not permitted for API key
404	`NOT_FOUND`	Resource not found
422	`VALIDATION_ERROR`	Struct/field validation failed (includes `fields` map with per-field errors)
429	`TOO_MANY_REQUESTS`	Rate limit exceeded
500	`INTERNAL_SERVER_ERROR`	Unexpected server error
503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable

Business Error Slugs

These slugs are returned with HTTP 400 when the trading core rejects a request:

Slug	Description
`REQUIRED_FIELD`	Missing required field
`INVALID_FORMAT`	Invalid field format or value
`INVALID_QUANTITY`	Amount is zero or violates constraints
`INVALID_PRICE`	Price is zero or negative
`INVALID_ORDER_TYPE`	Unknown order type
`INVALID_SIDE`	Unknown order side
`INVALID_STOP_PRICE`	Missing or invalid stop price for stop orders
`INVALID_PAIR`	Pair not found, disabled, or doesn't support this order type
`ORDER_NOT_FOUND`	Order doesn't exist or already completed
`INVALID_CURRENCY`	Invalid currency
`INVALID_PRECISION`	Invalid decimal precision
`INVALID_ORDER_SIZE`	Amount below `minimum_order_size` or above `maximum_order_size`
`INVALID_ORDER_VALUE`	Order value (amount × price) below `minimum_order_value`
`INSUFFICIENT_FUNDS`	Not enough available balance
`SERVICE_OVERLOADED`	Service temporarily overloaded, retry later
`INTERNAL_ERROR`	Internal service error

Examples

Handler error (BAD_REQUEST)

HTTP 400

{
    "code": "BAD_REQUEST",
    "message": "pair not found"
}

Business error from trading core

HTTP 400

{
    "code": "INSUFFICIENT_FUNDS",
    "message": "Out of balance: 0.5 BTC"
}

Validation error

HTTP 422

{
    "code": "VALIDATION_ERROR",
    "message": "Input data validation failed",
    "fields": {
        "order_type": "invalid order_type: FANTASY"
    }
}

Malformed JSON

HTTP 400

{
    "code": "MALFORMED_JSON",
    "message": "The request body is not a valid JSON"
}

Authentication Errors

Authentication errors return standard HTTP status codes with a descriptive message.

HTTP Status	Code	Description
401	`INVALID_SECRET`	API secret is incorrect
401	`UNAUTHORIZED`	General authentication failure (deleted key, inactive account, department mismatch)
403	`IP_NOT_ALLOWED`	Request IP is not in the API key whitelist
403	`FORBIDDEN`	Missing signature or insufficient permissions
403	`MISSING_SIGNATURE`	`X-SIGN` header required but not provided
403	`INVALID_SIGNATURE`	`X-SIGN` signature verification failed
404	`NOT_FOUND`	API key does not exist
422	`VALIDATION_ERROR`	Missing `api_key` or `api_secret` in request body