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 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 'groq/some-model' not found. It may have been retired, renamed, or never existed.",
    "type": "invalid_request_error",
    "status": 404
  }
}

Causes:

• Model name is misspelled
• Model has been retired — withdrawn by its provider, delisted, or the connection serving it was deactivated. A model that used to work and now returns this has almost certainly been retired.
• Model has been deprecated or renamed
• Model is not available in your account

This is the answer for a model that is not there. It used to be reported as a 403 GATEWAY1_AUTH_001 "Access denied to requested model", which sent people looking for a permission to acquire or an organization to join for a model that had simply been withdrawn. A 403 now means only what it says — see Forbidden Errors.

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.

context_data carries the threshold under both minimum_threshold and minimum_required — the same value under two names, because the gateway has always sent the first and the web app reads the second.

When the model is billed to your organization (org_billing_mode = 'org_pays'), the balance quoted is the organization's, not yours, and context_data.payer reads organization. Adding credits to your personal account will not clear it — an organization admin has to fund the organization.

Where the credit check applies

The check runs on every inference entry point, before the request reaches a provider — so a 402 means nothing was sent upstream and nothing was spent:

/v1/completions, /v1/embeddings, /v1/messages and /v1/images/generations gained the check on 2026-08-29; before that only /v1/chat/completions and /native/* carried it, and the other four were reconciled only after the fact by settlement. If you have code that relied on a request going through while the paying account was empty, it will now be refused up front.

The same rule applies whichever gateway is serving as the active inference server. Gateway Type 0 uses the GATEWAY0_BILLING_001 / GATEWAY0_BILLING_002 codes for the identical conditions — the message, the status and context_data are the same.

A model billed to an organization is checked against that organization's balance on every one of these endpoints, not just on chat completions.

Service Errors (503)

GATEWAY1_BILLING_002 - Invalid Model Price

{
  "error": {
    "code": "GATEWAY1_BILLING_002",
    "message": "Model openrouter/openrouter/auto is mispriced in the catalogue and cannot be billed. This is a platform fault, not a problem with your account — please contact support.",
    "type": "invalid_model_price",
    "status": 503
  }
}

Cause: the model's catalogue price is negative, which makes billing impossible to compute correctly. The request is refused before it reaches the provider, so you are not charged and no tokens are spent.

This is not a credit problem. Adding funds will not help — the fault is in our catalogue.

Solutions:

• Use a different model; other models are unaffected.
• Report the model id to support so the price can be corrected.
• Retry later: once the price is fixed the same request succeeds unchanged.

Applies on the same endpoints as the 402 above — see Where the credit check applies — and on Gateway Type 0 as GATEWAY0_BILLING_002.

Connection Test Errors

POST /api/connections/:id/test reports what happened to the test, not to your request. Three answers changed shape; callers should branch on code, never on the HTTP status alone (403 is now used by three different codes on this route).

internal_auth_failed exists because the health checker used to report exactly this condition as auth_failed: for months every automated check failed at our own front door and was recorded as "API key may be invalid" against connections whose credentials had never been contacted.

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

For a model, this now means exactly one thing: the model exists and is visible, and your account may not use it — someone else's individual model, or an organization model you are not a member of. A model that does not exist, or has been retired, answers 404 GATEWAY1_ROUTING_001 instead.

Solutions:

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

MASTER_ADMIN_AUTH_001 - Platform administrators only

Some /api/admin reads are not about your organization — they report on the whole platform, or on the platform organization itself. Being an admin of your own organization is not enough for those, and since 2026-08-29 they answer 403 MASTER_ADMIN_AUTH_001 instead of serving another tenant's data:

GET /api/admin/quotas/templates stays open to organization admins, but ?organization_id= is no longer taken on trust: naming an organization other than your own answers 403 rather than returning its templates. Omit the parameter to get your own. Platform admins may still name any organization.

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