API Errors

This guide provides a comprehensive reference for all API errors you may encounter when using LangMart, along with solutions for each.

Authentication Errors (401)

Authentication errors occur when your API key is invalid, missing, or expired.

GATEWAY1_AUTH_001 - Invalid API Key

{
  "error": {
    "code": "GATEWAY1_AUTH_001",
    "message": "Invalid API key",
    "type": "authentication_error",
    "status": 401
  }
}

Causes:

• API key is incorrect or misspelled
• API key has been deleted or revoked
• API key belongs to a different environment

Solutions:

1. Verify your API key in the dashboard under Settings > API Keys
2. Ensure you're using the correct format: Authorization: Bearer YOUR_KEY
3. Generate a new API key if needed

Provider Authentication Errors

To update provider keys:

1. Go to Connections in the dashboard
2. Find the failing connection
3. Click Edit and enter the new API key
4. Click Test to verify

Validation Errors (400)

Validation errors occur when your request format or parameters are invalid.

API_VALIDATION_001 - Invalid Request

{
  "error": {
    "code": "API_VALIDATION_001",
    "message": "Invalid request format",
    "type": "invalid_request_error",
    "status": 400
  }
}

Common Causes:

• Missing required fields
• Invalid JSON format
• Incorrect parameter types
• Unsupported parameter values

Solutions:

Check required fields:

{
  "model": "gpt-4o",           // Required
  "messages": [                 // Required
    {
      "role": "user",          // Required: "user", "assistant", or "system"
      "content": "Hello"       // Required
    }
  ]
}

PROVIDER_ANTHROPIC_400 - Invalid Anthropic Request

Anthropic has specific requirements:

// Correct Anthropic format
{
  "model": "claude-3-sonnet-20240229",
  "max_tokens": 1024,           // Required for Anthropic
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

Common Anthropic issues:

• Missing max_tokens (required)
• System messages must use system parameter, not in messages array
• Invalid model names

PROVIDER_ANTHROPIC_413 - Request Too Large

{
  "error": {
    "code": "PROVIDER_ANTHROPIC_413",
    "message": "Request exceeds Anthropic size limit",
    "status": 413
  }
}

Solution: Reduce your prompt size or split into multiple requests.

Model Not Found (404)

GATEWAY1_ROUTING_001 - Model Not Found

{
  "error": {
    "code": "GATEWAY1_ROUTING_001",
    "message": "Model not found",
    "type": "not_found",
    "status": 404
  }
}

Causes:

• Model name is misspelled
• Model has been deprecated or renamed
• Model is not available in your account

Solutions:

1. Check available models:

curl -X GET "https://api.langmart.ai/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Use the correct model identifier format: provider/model-name

PROVIDER_OPENROUTER_POLICY - Data Policy Restriction

{
  "error": {
    "code": "PROVIDER_OPENROUTER_POLICY",
    "message": "OpenRouter data policy restriction - free models require data sharing",
    "status": 404
  }
}

Solution:

1. Go to https://openrouter.ai/settings/privacy
2. Enable data sharing for free models
3. Or use a paid model instead

Rate Limit Errors (429)

Provider Rate Limits

{
  "error": {
    "code": "PROVIDER_OPENAI_429",
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "status": 429
  },
  "retry_after": 60
}

Response Headers:

Retry-After: 60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T14:30:00Z

Solutions:

1. Wait for Retry-After seconds before retrying
2. Implement exponential backoff
3. Spread requests across multiple providers
4. Upgrade to higher tier with provider

Billing Errors (402)

GATEWAY1_BILLING_001 - Insufficient Credits

{
  "error": {
    "code": "GATEWAY1_BILLING_001",
    "message": "Insufficient credits. Your balance ($0.05) is below the minimum required ($0.10).",
    "type": "billing_error",
    "status": 402
  }
}

Solution: Add credits to your account. See Billing Issues.

Forbidden Errors (403)

GATEWAY1_AUTH_002 - Access Denied

{
  "error": {
    "code": "GATEWAY1_AUTH_002",
    "message": "Access denied",
    "type": "forbidden",
    "status": 403
  }
}

Causes:

• Insufficient permissions
• Resource belongs to another organization
• Feature not available on your plan

Solutions:

1. Check your organization membership
2. Verify you have access to the requested resource
3. Contact your organization admin

Server Errors (500+)

SYSTEM_DB_001 - Database Error

{
  "error": {
    "code": "SYSTEM_DB_001",
    "message": "Database operation failed",
    "type": "api_error",
    "status": 500
  }
}

Solution: This is usually temporary. Wait and retry. If persistent, contact support.

Gateway Errors (503/504)

GATEWAY3_CONN_001 - Gateway Unavailable

{
  "error": {
    "code": "GATEWAY3_CONN_001",
    "message": "Gateway temporarily unavailable",
    "status": 503
  }
}

GATEWAY_TIMEOUT_001 - Gateway Timeout

{
  "error": {
    "code": "GATEWAY_TIMEOUT_001",
    "message": "Gateway did not respond within 60s",
    "type": "gateway_timeout",
    "status": 504
  },
  "retry_after": 5,
  "gateway_id": "gw-123",
  "gateway_type": "type3"
}

Solutions:

1. Retry with exponential backoff
2. Check system status for outages
3. Reduce request size for timeout errors
4. Use streaming for large responses

Routing Errors (503)

ROUTE_SELECTION_FAILED - All Routes Failed

{
  "error": {
    "code": "ROUTE_SELECTION_FAILED",
    "message": "Unable to route to any available model",
    "status": 503
  }
}

Causes:

• All configured connections are failing
• No healthy targets available
• Circuit breakers are open

Solutions:

1. Check connection status in dashboard
2. Test individual connections
3. Verify provider API keys
4. Wait for circuit breakers to reset

Other Routing Errors

Provider-Specific Errors

Anthropic

Google AI

Error Code Reference Table

Best Practices for Error Handling

Implement Comprehensive Error Handling

import requests

def make_langmart_request(data):
    try:
        response = requests.post(
            "https://api.langmart.ai/v1/chat/completions",
            headers={"Authorization": "Bearer YOUR_KEY"},
            json=data,
            timeout=120
        )

        if response.status_code == 200:
            return response.json()

        error = response.json().get('error', {})
        error_code = error.get('code')

        # Handle specific errors
        if response.status_code == 401:
            raise AuthenticationError(f"Auth failed: {error.get('message')}")

        if response.status_code == 402:
            raise BillingError("Insufficient credits")

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            raise RateLimitError(f"Rate limited, retry after {retry_after}s")

        if response.status_code >= 500:
            raise ServerError(f"Server error: {error_code}")

        raise APIError(f"Request failed: {error.get('message')}")

    except requests.Timeout:
        raise TimeoutError("Request timed out")
    except requests.ConnectionError:
        raise ConnectionError("Failed to connect")

Log Errors for Debugging

Always include the request ID in your logs:

response = requests.post(...)
request_id = response.headers.get('x-request-id')

if not response.ok:
    logger.error(f"Request {request_id} failed: {response.json()}")

Related Documentation

• Connection Issues - Network troubleshooting
• Billing Issues - Payment problems
• Error Tracking - Monitor errors