A.5 Error Codes Contract

Comprehensive error handling is essential for reliable SSO (OAuth) integration. This section defines the standard error codes, their meanings, and appropriate handling procedures for all API interactions.

HTTP Status Code Overview

Standard HTTP Status Codes

Status Code	Designation	General Usage
200	OK	Request successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Authentication failure
403	Forbidden	Permission denied
404	Not Found	Resource not found
410	Gone	Resource expired
417	Expectation Failed	Invalid token format

SSO (OAuth) Specific Error Codes

400 - Bad Request

Description: This error occurs when at least one required field is not specified or request parameters are malformed.

Common Causes:

• Missing required query parameters
• Invalid JSON format in request body
• Malformed URL parameters
• Missing broker identification parameters

Response Example:

{
    "error": "Bad Request",
    "message": "Required parameter 'token' is missing",
    "code": "MISSING_REQUIRED_PARAMETER"
}

403 - Forbidden

Description: Access denied due to authentication failure or insufficient permissions.

Error Cases:

CH_CLIENT_AUTH_FAILURE

• Cause: Invalid password in API call 4.1 or invalid crmApiToken in API calls 4.2-4.4
• Action: Verify authentication credentials and token validity
• Response Example:

{
    "error": "Forbidden",
    "message": "Client authentication failed",
    "code": "CH_CLIENT_AUTH_FAILURE"
}

CH_INSUFFICIENT_PERMISSIONS

• Cause: Broker lacks access rights due to manager.disabledBrokerName configuration
• Action: Check broker permissions and manager settings
• Response Example:

{
    "error": "Forbidden", 
    "message": "Insufficient permissions for broker",
    "code": "CH_INSUFFICIENT_PERMISSIONS"
}

404 - Not Found

Description: Requested resource not found in the broker's backend.

Error Cases:

OT Token Not Found

• API Call: 4.2 - Verify and exchange OT token
• Cause: OT token (code) not found in broker's backend
• Action: Verify token generation and storage processes

Long-term Access Token Not Found

• API Call: 4.3 - Verify long-term access token
• Cause: Access token (accessToken) not found in broker's backend
• Action: Check token storage and user session management

User Identifier Not Found

• API Call: 4.4 - Generate OT token for InApp action
• Cause: User identifier (userId) not found in broker's backend
• Action: Verify user existence and database integrity

Response Example:

{
    "error": "Not Found",
    "message": "OT token not found",
    "code": "TOKEN_NOT_FOUND"
}

410 - Gone

Description: Resource has expired and is no longer available.

CID_TOKEN_EXPIRED

• Cause: Expired token used to access broker's backend
• Action: Implement token refresh mechanism
• Response Example:

{
    "error": "Gone",
    "message": "Token has expired",
    "code": "CID_TOKEN_EXPIRED"
}

417 - Expectation Failed

Description: Invalid token format or structure.

CID_NON_EXISTED_TOKEN

• Cause: Invalid token format used to access broker's backend
• Action: Validate token format before processing
• Response Example:

{
    "error": "Expectation Failed",
    "message": "Invalid token format",
    "code": "CID_NON_EXISTED_TOKEN"
}

Financial Field Format Errors

Balance and Monetary Values

Financial fields use the moneyDigits multiplier for precise decimal representation.

Error Example:

{
    "error": "Bad Request",
    "message": "Invalid balance format. Expected value in 10^moneyDigits format",
    "code": "INVALID_MONETARY_FORMAT",
    "example": "Balance 2345.12 should be sent as 234512 with moneyDigits=2"
}

Required Financial Fields

• balance: Account balance
• bonus: Bonus amount
• nonWithdrawableBonus: Non-withdrawable bonus
• equity: Account equity
• usedMargin: Used margin
• freeMargin: Free margin

Broker Identification Errors

Missing Broker Parameters

{
    "error": "Bad Request",
    "message": "Required broker identification parameters missing",
    "code": "BROKER_ID_MISSING",
    "required": ["brokerName", "brokerCrmName"]
}

Invalid Broker Parameters

{
    "error": "Unauthorized",
    "message": "Invalid broker identification parameters",
    "code": "BROKER_ID_INVALID"
}

Broker Access Denied

{
    "error": "Forbidden",
    "message": "Broker access denied",
    "code": "BROKER_ACCESS_DENIED",
    "brokerName": "invalid_broker"
}

Rate Limiting Errors

Exceeded Rate Limits

{
    "error": "Too Many Requests",
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "retryAfter": 3600,
    "limit": 1000,
    "window": "hour"
}

Rate Limit Rules:

• No rate limits for GET requests
• Rate limits apply to PUT/POST/DELETE requests
• Limits based on requests per hour
• Automatic rejection when threshold exceeded

Error Response Format

Standard Error Response Structure

{
    "error": "Error Type",
    "message": "Human-readable error description",
    "code": "MACHINE_READABLE_CODE",
    "timestamp": "2023-01-01T12:00:00Z",
    "requestId": "req_123456789",
    "details": {
        "field": "additional context",
        "value": "problematic value"
    }
}

Validation Error Response

{
    "error": "Bad Request",
    "message": "Request validation failed",
    "code": "VALIDATION_ERROR",
    "validationErrors": [
        {
            "field": "email",
            "message": "Invalid email format",
            "value": "invalid-email"
        },
        {
            "field": "password", 
            "message": "Password too short",
            "value": "123"
        }
    ]
}

Error Handling Best Practices

Client-Side Handling

1. Check HTTP Status First: Use status code for primary error categorization
2. Parse Error Code: Use machine-readable code for specific error handling
3. User Messages: Display user-friendly messages based on error type
4. Retry Logic: Implement appropriate retry mechanisms for transient errors

Server-Side Logging

1. Comprehensive Logging: Log all errors with full context
2. Correlation IDs: Include request IDs for troubleshooting
3. Security: Never log sensitive data like passwords or tokens
4. Monitoring: Set up alerts for critical error patterns

Recovery Strategies

1. Authentication Errors: Prompt for re-authentication
2. Token Errors: Implement token refresh flows
3. Rate Limits: Implement exponential backoff
4. Validation Errors: Highlight specific form fields

Testing Error Scenarios

Required Test Cases

• Missing required parameters
• Invalid parameter formats
• Expired tokens
• Invalid authentication credentials
• Rate limit scenarios
• Network connectivity issues

Error Response Validation

• Verify correct HTTP status codes
• Validate error response format
• Test error message clarity
• Confirm error code consistency

This error handling framework ensures reliable integration and provides clear guidance for troubleshooting SSO (OAuth) implementation issues.