API Reference

Errors

NeuronEdge uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error with your request. Codes in the 5xx range indicate an error on our end.

Error Response Format

All error responses include a JSON body with details about the error:

json

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401,
    "request_id": "01HXYZ123ABC456DEF"
  }
}

HTTP Status Codes

Code	Name	Description
400	Bad Request	The request was malformed or missing required parameters.
401	Unauthorized	Authentication failed. Check your API key.
403	Forbidden	You don't have permission to access this resource.
404	Not Found	The requested resource doesn't exist.
422	Unprocessable Entity	The request was valid but couldn't be processed.
429	Too Many Requests	Rate limit exceeded. Slow down and retry.
500	Internal Server Error	Something went wrong on our end.
502	Bad Gateway	Error communicating with the upstream LLM provider.
503	Service Unavailable	The service is temporarily unavailable.
504	Gateway Timeout	The upstream LLM provider took too long to respond.

Error Codes

In addition to HTTP status codes, responses include specific error codes:

INVALID_API_KEY

The NeuronEdge API key is missing, invalid, or revoked.

MISSING_PROVIDER_KEY

The X-Provider-API-Key header is missing.

INVALID_PROVIDER_KEY

The LLM provider rejected the API key.

RATE_LIMIT_EXCEEDED

You've exceeded your rate limit. Check X-RateLimit-* headers.

QUOTA_EXCEEDED

You've exceeded your monthly request quota.

POLICY_NOT_FOUND

The specified policy ID doesn't exist.

INVALID_ENTITY_TYPE

One or more entity types in the policy are invalid.

PROVIDER_ERROR

The upstream LLM provider returned an error.

FEATURE_NOT_AVAILABLE

This feature is not available on your subscription tier.

Handling Errors

typescript

try {
  const response = await fetch('https://api.neuronedge.ai/v1/openai/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ne_live_your_api_key',
      'X-Provider-API-Key': 'sk-your-openai-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ model: 'gpt-5.2', messages: [...] }),
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.error.code) {
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        // Retry request
        break;
      case 'INVALID_API_KEY':
        // Check API key configuration
        throw new Error('Invalid API key');
      case 'PROVIDER_ERROR':
        // Handle provider-specific error
        console.error('Provider error:', error.error.message);
        break;
      default:
        throw new Error(error.error.message);
    }
  }
} catch (error) {
  console.error('Request failed:', error);
}

Health Check Endpoints

Use these endpoints to check service health (no authentication required):

GET /health

Basic health check

GET /health/ready

Readiness probe for Kubernetes

GET /health/db

Database connectivity check