Skip to main content
All Bluum errors follow the pattern BLUM-{HTTP_STATUS}-{SEQUENCE}. This page provides the complete catalog.

​
400 — Bad Request

Validation failures and malformed requests.
CodeMessageResolution
BLUM-400-001Generic validation errorCheck the error message for specific field details
BLUM-400-002Missing required fieldInclude all required fields in your request
BLUM-400-003Invalid field formatMatch expected types: dates as ISO 8601, phone as E.164, country as ISO alpha-2
BLUM-400-004Invalid enum valueUse one of the documented enum values
BLUM-400-005Invalid amountAmount must be a positive decimal string (e.g., "100.00")
BLUM-400-006Invalid quantityQuantity must be a positive number
BLUM-400-007Invalid date rangeStart date must be before end date
BLUM-400-008Request body too largeReduce payload size (file uploads: max 10MB)

​
401 — Unauthorized

Authentication failures.
CodeMessageResolution
BLUM-401-001Missing authorization headerInclude Authorization: Basic <credentials>
BLUM-401-002Malformed authorization headerFormat: Basic <base64(API_KEY:API_SECRET)>
BLUM-401-003Invalid API key or secretVerify credentials are correct and not revoked
BLUM-401-004API key inactiveContact support to activate your API key
BLUM-401-005API key expiredGenerate new credentials in the dashboard

​
403 — Forbidden

Authorization and permission errors.
CodeMessageResolution
BLUM-403-001Insufficient permissionsYour API key doesn’t have access to this resource
BLUM-403-002Account not approvedComplete KYC verification before trading
BLUM-403-003Production access requiredRequest production access from support
BLUM-403-004Operation not allowedThe current account state doesn’t permit this operation

​
404 — Not Found

Resource doesn’t exist or isn’t accessible.
CodeMessageResolution
BLUM-404-001Resource not foundVerify the ID exists and belongs to your tenant
BLUM-404-002Endpoint not foundCheck the URL path against the API reference
BLUM-404-003Asset not foundVerify the symbol or asset ID

​
409 — Conflict

Duplicate resources or state conflicts.
CodeMessageResolution
BLUM-409-001Duplicate resourceResource with these attributes already exists
BLUM-409-002Idempotency conflictSame idempotency key used with different request body
BLUM-409-003State conflictResource is in a state that prevents this operation

​
422 — Unprocessable Entity

Business rule violations.
CodeMessageResolution
BLUM-422-001Insufficient fundsWallet balance too low for this operation
BLUM-422-002Market closedPlace order during market hours or use gtc
BLUM-422-003Asset not tradableThis asset is not available for trading
BLUM-422-004Position insufficientNot enough shares to sell
BLUM-422-005Withdrawal limit exceededExceeds available withdrawal balance

​
429 — Too Many Requests

Rate limit exceeded.
CodeMessageResolution
BLUM-429-001Rate limit exceededWait and retry with exponential backoff; check Retry-After header

​
500 — Internal Server Error

Server-side errors. These are retryable.
CodeMessageResolution
BLUM-500-001Internal errorRetry with exponential backoff; contact support if persistent
BLUM-500-017External service errorUpstream service temporarily unavailable; retry

​
Handling errors programmatically

async function handleBluumResponse(response) {
  if (response.ok) return response.json();

  const error = await response.json();
  const [, status] = error.code.match(/BLUM-(\d+)-/) || [];

  switch (status) {
    case '400': // Fix request and don't retry
    case '401': // Fix credentials
    case '403': // Fix permissions
    case '404': // Fix resource ID
    case '422': // Fix business logic
      throw new Error(`Client error: ${error.code} - ${error.message}`);

    case '429': // Retry with backoff
      const retryAfter = response.headers.get('Retry-After') || 1;
      await sleep(retryAfter * 1000);
      return retry();

    case '500': // Retry with backoff
      await sleep(1000);
      return retry();
  }
}