Error Codes

All API errors return a consistent JSON structure. The GlobalExceptionFilter normalizes every error -- including validation errors, domain exceptions, and unhandled crashes -- into this format.

Response Format

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "message": "Field 'amount' must be a positive number"
}

Field	Type	Description
`statusCode`	`number`	HTTP status code (400, 401, 403, 404, 429, 500)
`code`	`string`	Machine-readable error code for programmatic handling
`message`	`string`	Human-readable description of the error

Error Codes by Status

400 Bad Request

Code	Description	Example
`VALIDATION_ERROR`	Request body failed DTO validation	Missing required field, invalid type, value out of range
`NONCE_EXPIRED`	Auth nonce expired or not found	Wallet verification took too long, nonce was consumed
`ORDER_FAILED`	Order could not be placed	Insufficient balance, market closed, invalid order parameters
`SELF_REFERRAL`	User tried to use their own access key	Referral code belongs to the authenticated user
`INVALID_CODE_FORMAT`	Access key format is invalid	Code must be 4-12 alphanumeric characters
`INSUFFICIENT_BALANCE`	Not enough funds for the operation	Paper trading balance too low, merge/split insufficient shares

401 Unauthorized

Code	Description	Example
`UNAUTHORIZED`	Missing or invalid JWT token	No Bearer token, expired access token
`INVALID_SIGNATURE`	Wallet signature verification failed	Signature does not match the expected message
`INVALID_REFRESH_TOKEN`	Refresh token is invalid or expired	Token was revoked, rotated, or past its 7-day TTL

403 Forbidden

Code	Description	Example
`FORBIDDEN`	User does not have permission	Accessing another user's resource, insufficient tier
`NOT_ELIGIBLE`	User is not eligible for the action	Cannot generate access key, mission requirements not met

404 Not Found

Code	Description	Example
`NOT_FOUND`	Resource does not exist	Market, order, or user not found
`USER_NOT_FOUND`	User account not found	Wallet address has no associated account
`MARKET_NOT_FOUND`	Market does not exist	Invalid market slug or ID
`ORDER_NOT_FOUND`	Order does not exist	Attempting to cancel a nonexistent order
`MISSION_NOT_FOUND`	Mission does not exist	Invalid mission ID

409 Conflict

Code	Description	Example
`ALREADY_REFERRED`	User already has a referral	Cannot apply a second referral code
`CODE_TAKEN`	Access key code already in use	Another user has claimed this custom code

429 Too Many Requests

Code	Description	Example
`RATE_LIMITED`	Request rate limit exceeded	More than 100 requests per minute from the same IP

500 Internal Server Error

Code	Description	Example
`INTERNAL_ERROR`	Unexpected server error	Unhandled exception, database connection failure

Validation Errors

When request body validation fails via class-validator, the GlobalExceptionFilter joins all validation messages into a single comma-separated string and forces the code to VALIDATION_ERROR:

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "message": "amount must be a positive number, side must be one of: YES, NO"
}

The validation pipe is configured with whitelist: true (strips unknown properties), transform: true (auto-coerces types), and forbidNonWhitelisted: true (rejects unknown fields).

How Errors Are Generated

Domain Errors

Backend services throw ApiException for business logic errors with a specific code:

throw new ApiException(
  'ORDER_FAILED',
  'Insufficient balance to place this order',
  HttpStatus.BAD_REQUEST,
);

Default Code Mapping

When an error does not include an explicit code (e.g., a raw HttpException), the GlobalExceptionFilter maps the HTTP status to a default code:

Status	Default Code
400	`VALIDATION_ERROR`
401	`UNAUTHORIZED`
403	`FORBIDDEN`
404	`NOT_FOUND`
429	`RATE_LIMITED`
Other	`INTERNAL_ERROR`

Client-Side Handling

The frontend API client (lib/api/client.ts) throws an ApiClientError with the full error body. Handle errors by checking the code field:

try {
  await placeOrder(orderData);
} catch (error) {
  if (error instanceof ApiClientError) {
    switch (error.body.code) {
      case 'ORDER_FAILED':
        showToast('Order failed: ' + error.body.message);
        break;
      case 'UNAUTHORIZED':
        // 401 retry is handled automatically by the client
        break;
      default:
        showToast('Something went wrong');
    }
  }
}

The API client automatically handles 401 errors by refreshing the access token and retrying the request. You do not need to handle UNAUTHORIZED errors manually in most cases.

On this page