Fig API Error Documentation

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

This document provides comprehensive information about error handling in the Fig API, including HTTP status codes, error response formats, and common error scenarios for both REST and WebSocket endpoints.

Table of Contents

• HTTP Error Responses
• WebSocket Error Responses
• Authentication Errors
• Rate Limiting Errors
• Validation Errors
• Business Logic Errors
• Common Error Scenarios
• Error Handling Best Practices

HTTP Error Responses

Standard Error Response Format

All HTTP error responses follow a consistent JSON structure:

{
  "code": 400,
  "message": "Bad Request",
  "reason": [
    "Invalid input parameter",
    "Missing required field"
  ]
}

HTTP Status Codes

Error Response Examples

400 Bad Request

{
  "code": 400,
  "message": "Invalid Request",
  "reason": [
    "Invalid expiry date format: 2024-13-45",
    "Direction must be \"bid\" or \"ask\""
  ]
}

401 Unauthorized

{
  "code": 401,
  "message": "Missing bearer token"
}

403 Forbidden

{
  "code": 403,
  "message": "Access denied"
}

404 Not Found

{
  "code": 404,
  "message": "Not Found"
}

429 Too Many Requests

{
  "code": 429,
  "message": "Rate limit exceeded"
}

Rate Limit Headers:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when the rate limit resets

500 Internal Server Error

{
  "code": 500,
  "message": "Internal Server Error",
  "reason": [
    "Failed to process request"
  ]
}

WebSocket Error Responses

JSON-RPC Error Format

WebSocket endpoints use JSON-RPC 2.0 protocol and return errors in the following format:

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {
      "additional": "error details"
    }
  }
}

JSON-RPC Error Codes

WebSocket Error Examples

Parse Error (-32700)

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32700,
    "message": "Parse error"
  }
}

Method Not Found (-32601)

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Rate Limit Exceeded (-32603)

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32603,
    "message": "Rate limit exceeded",
    "data": {
      "limit": 100,
      "window": "1m0s",
      "reset": 1640995200
    }
  }
}

Authentication Errors

Common Authentication Error Messages

Authentication Error Examples

Missing Token

{
  "code": 401,
  "message": "missing bearer token"
}

Invalid Token

{
  "code": 401,
  "message": "authorisation token expired or not valid"
}

Insufficient Permissions

{
  "code": 403,
  "message": "insufficient permissions"
}

Rate Limiting Errors

Rate Limiting Configuration

The Fig API implements distributed rate limiting using Redis:

• Default HTTP Limit: 100 requests per minute
• Default WebSocket Limit: 100 messages per minute
• Key Strategy: User ID for authenticated requests, IP address for unauthenticated requests

Rate Limit Error Response

HTTP (429 Status)

{
  "code": 429,
  "message": "rate limit exceeded"
}

WebSocket (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32603,
    "message": "Rate limit exceeded",
    "data": {
      "limit": 100,
      "window": "1m0s",
      "reset": 1640995200
    }
  }
}

Rate Limit Headers (HTTP Only)

When rate limit is exceeded, the following headers are included in the response:

• X-RateLimit-Limit: Maximum requests allowed (e.g., "100")
• X-RateLimit-Remaining: Remaining requests in current window (e.g., "0")
• X-RateLimit-Reset: Unix timestamp when rate limit resets (e.g., "1640995200")

Validation Errors

Common Validation Error Messages

Validation Error Examples

Invalid Date Format

{
  "code": 400,
  "message": "Invalid Request",
  "reason": [
    "invalid expiry date format: 2024-13-45"
  ]
}

Multiple Validation Errors

{
  "code": 400,
  "message": "Invalid Request",
  "reason": [
    "Direction must be \"bid\" or \"ask\"",
    "Invalid price format",
    "Amount must be greater than 0"
  ]
}

Business Logic Errors

RFQ (Request for Quote) Errors

Exchange and Instrument Errors

User and Account Errors

Desk and Entity Errors

Common Error Scenarios

1. Invalid Authentication

Scenario: Making a request without proper authentication.

Request:

GET /v1/rfq/123

Response:

{
  "code": 401,
  "message": "missing bearer token"
}

Solution: Include a valid Bearer token in the Authorization header.

2. Rate Limit Exceeded

Scenario: Making too many requests in a short time period.

Response:

{
  "code": 429,
  "message": "rate limit exceeded"
}

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

Solution: Wait until the rate limit window resets or implement exponential backoff.

3. Resource Not Found

Scenario: Requesting a resource that doesn't exist.

Request:

GET /v1/rfq/999999

Response:

{
  "code": 404,
  "message": "Not Found"
}

Solution: Verify the resource ID exists and is accessible to your account.

4. Validation Errors

Scenario: Submitting invalid data in a request.

Request:

{
  "direction": "invalid",
  "price": -100
}

Response:

{
  "code": 400,
  "message": "Invalid Request",
  "reason": [
    "Direction must be \"bid\" or \"ask\"",
    "Price must be greater than 0"
  ]
}

Solution: Review the validation errors and correct the request data.

5. WebSocket Connection Errors

Scenario: Invalid JSON-RPC message format.

Request:

{
  "method": "v1/subscribe",
  "params": "invalid"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32700,
    "message": "Parse error"
  }
}

Solution: Ensure the message follows JSON-RPC 2.0 format.

Error Handling Best Practices

1. Always Check Status Codes

Always check the HTTP status code before processing the response body. A 2xx status code indicates success, while 4xx and 5xx indicate errors.

2. Handle Rate Limiting Gracefully

When receiving a 429 status code:

• Implement exponential backoff
• Respect the X-RateLimit-Reset header
• Consider implementing request queuing

3. Validate Request Data

Before making requests:

• Validate all required fields are present
• Ensure data types match expected formats
• Check for reasonable value ranges

4. Implement Retry Logic

For transient errors (5xx status codes):

• Implement retry logic with exponential backoff
• Set maximum retry attempts
• Log retry attempts for debugging

5. Handle WebSocket Errors

For WebSocket connections:

• Always check the error field in JSON-RPC responses
• Implement reconnection logic for connection failures
• Handle rate limiting errors appropriately

6. Log Error Details

When errors occur:

• Log the full error response for debugging
• Include request context (endpoint, parameters, user ID)
• Monitor error patterns for system issues

7. User-Friendly Error Messages

For end-user applications:

• Translate technical error messages to user-friendly language
• Provide actionable guidance when possible
• Hide sensitive information in error messages

Error Response Schema

HTTP Error Response Schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "integer",
      "description": "HTTP status code"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "reason": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Detailed error reasons"
    }
  },
  "required": ["code", "message"]
}

WebSocket Error Response Schema

{
  "type": "object",
  "properties": {
    "jsonrpc": {
      "type": "string",
      "const": "2.0"
    },
    "id": {
      "type": "integer",
      "description": "Request ID"
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "description": "JSON-RPC error code"
        },
        "message": {
          "type": "string",
          "description": "Error message"
        },
        "data": {
          "type": "object",
          "description": "Additional error data"
        }
      },
      "required": ["code", "message"]
    }
  },
  "required": ["jsonrpc", "error"]
}

Support and Troubleshooting

If you encounter errors not documented here or need assistance with error handling:

1. Check the API Documentation: Ensure you're using the correct endpoint and parameters
2. Review Request Format: Verify your request follows the expected format
3. Check Authentication: Ensure your authentication token is valid and not expired
4. Monitor Rate Limits: Check if you're approaching or exceeding rate limits
5. Contact Support: If the issue persists, contact the Fig API support team with:
   • Full error response
   • Request details (endpoint, parameters, timestamp)
   • Your application context

Version History

• v1.0: Initial error documentation
• Includes HTTP and WebSocket error handling
• Covers authentication, validation, and business logic errors
• Provides best practices and troubleshooting guidance