Error Handling

This guide covers the error response format and error codes used by the PRIME API.

Error Response Format

All errors return a JSON object with the following structure:

{
  "code": 400,
  "message": "Invalid quantity: must be positive",
  "status": "INVALID_ARGUMENT",
  "details": []
}

Fields

HTTP Status Codes

Client Errors (4xx)

Server Errors (5xx)

Error Reasons

The API uses specific reason codes to indicate the type of error.

Authentication & Authorization

Validation Errors

Resource Errors

Trading Errors

Deposit/Withdrawal Errors

System Errors

Resource Names

Errors may include a resource name indicating which entity caused the error.

Error Examples

Invalid Request

{
  "code": 400,
  "message": "quantity: must be greater than 0",
  "status": "INVALID_ARGUMENT",
  "details": []
}

Authentication Failed

{
  "code": 401,
  "message": "JWT token was invalid",
  "status": "UNAUTHENTICATED",
  "details": []
}

MFA Required

When MFA is enabled for a user but the TOTP code (challenge field) was not provided in the login request:

{
  "code": 16,
  "message": "MFA challenge required",
  "details": [{
    "@type": "type.googleapis.com/tgtraded.Error",
    "reason": "MFA_REQUIRED"
  }]
}

To resolve, re-submit the login request with the challenge field containing the TOTP code.

Permission Denied

{
  "code": 403,
  "message": "User does not have trade permission on sub-account",
  "status": "PERMISSION_DENIED",
  "details": []
}

Resource Not Found

{
  "code": 404,
  "message": "Order not found",
  "status": "NOT_FOUND",
  "details": [{
    "resource": "ORDER",
    "id": "order-uuid"
  }]
}

Insufficient Funds

{
  "code": 403,
  "message": "Insufficient CHF balance: required 50000.00, available 25000.00",
  "status": "FAILED_PRECONDITION",
  "details": [{
    "reason": "NOT_ENOUGH_FUNDS",
    "resource": "BALANCE",
    "required": "50000.00",
    "available": "25000.00"
  }]
}

Rate Limited

{
  "code": 429,
  "message": "Rate limit exceeded. Retry after 60 seconds",
  "status": "RESOURCE_EXHAUSTED",
  "details": [{
    "reason": "SERVER_EXHAUSTED",
    "retry_after": 60
  }]
}

Handling Errors

Best Practices

1. Check HTTP status code first - Categorize by 4xx vs 5xx
2. Parse the error response - Extract message and details
3. Handle specific reasons - Implement logic for expected errors
4. Log unexpected errors - Include correlation ID for support
5. Implement retries for 5xx - Use exponential backoff

Example Error Handler (JavaScript)

async function apiRequest(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    const error = await response.json();
    switch (error.status) {
      case 'UNAUTHENTICATED':
        // Refresh token or redirect to login
        if (error.details?.some(d => d.reason === 'MFA_REQUIRED')) {
          return handleMfaChallenge(error.details);
        }
        return redirectToLogin();
      case 'PERMISSION_DENIED':
        throw new Error('You do not have permission for this action');
      case 'NOT_FOUND':
        throw new Error('Resource not found');
      case 'RESOURCE_EXHAUSTED':
        // Implement retry with backoff
        const retryAfter = error.details?.[0]?.retry_after || 60;
        await sleep(retryAfter * 1000);
        return apiRequest(url, options);
      default:
        throw new Error(error.message || 'An error occurred');
    }
  }
  return response.json();
}

Retry Strategy

For transient errors (5xx, rate limits):

async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      if (error.status >= 500 || error.status === 429) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await sleep(delay);
      } else {
        throw error; // Don't retry client errors
      }
    }
  }
}

Correlation ID

Every request is assigned a correlation ID for tracing. Include this ID when contacting support.

Finding the Correlation ID

1. Check response headers: X-Correlation-ID
2. Check error details: may include correlation_id field

Providing Your Own

You can provide a correlation ID in the request:

curl -X GET "https://api.t-dx.com/api/rest/v1/orders" \
  -H "Authorization: Bearer <token>" \
  -H "X-Correlation-ID: your-uuid-here"