Error Codes

All API errors follow a consistent format and include helpful information for debugging.

Error Response Format

{
  "error": "error_code",
  "message": "Human-readable description of the error",
  "field": "field_name",
  "details": {}
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn't exist
422	Validation Error	Request body validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error (contact support)
503	Service Unavailable	Temporarily unavailable

Common Error Codes

Validation Errors (400/422)

Error Code	Description	Solution
validation_error	Request body validation failed	Check field types and ranges
invalid_latitude	Latitude out of range	Must be -90 to 90
invalid_longitude	Longitude out of range	Must be -180 to 180
invalid_capacity	Capacity must be positive	Use positive number
invalid_objective	Unknown objective	Use: energy, lcoe, npv, irr
missing_field	Required field missing	Include all required fields

Example:

{
  "error": "validation_error",
  "message": "latitude must be between -90 and 90",
  "field": "latitude",
  "details": {
    "provided": 95.0,
    "min": -90,
    "max": 90
  }
}

Authentication Errors (401/403)

Error Code	Description	Solution
missing_api_key	No API key provided	Add X-API-Key header
invalid_api_key	API key not recognized	Check key is correct
expired_api_key	API key has expired	Generate new key
invalid_token	JWT token invalid	Re-authenticate
expired_token	JWT token expired	Refresh token
insufficient_permissions	Lacks required permission	Contact admin

Example:

{
  "error": "invalid_api_key",
  "message": "The provided API key is not valid",
  "details": {
    "hint": "Check that your API key is correctly copied from the dashboard"
  }
}

Rate Limit Errors (429)

Error Code	Description	Solution
rate_limit_exceeded	Too many requests	Wait and retry
concurrent_limit	Too many concurrent jobs	Wait for jobs to complete

Example:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "details": {
    "limit": 100,
    "remaining": 0,
    "reset_at": "2026-01-25T12:00:00Z",
    "retry_after": 60
  }
}

Job Errors

Error Code	Description	Solution
job_not_found	Job ID doesn't exist	Check job ID
job_expired	Job results expired	Re-run optimization
job_failed	Optimization failed	Check parameters

Example:

{
  "error": "job_not_found",
  "message": "Optimization job not found",
  "details": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "hint": "Job results are stored for 24 hours"
  }
}

Server Errors (500/503)

Error Code	Description	Solution
internal_error	Unexpected server error	Retry or contact support
service_unavailable	Temporary outage	Retry later
model_error	ML model error	Contact support

Handling Errors

Python

import requests

response = requests.post(url, json=data)

if response.status_code == 200:
    result = response.json()
elif response.status_code == 422:
    error = response.json()
    print(f"Validation error: {error['message']}")
    print(f"Field: {error.get('field')}")
elif response.status_code == 429:
    error = response.json()
    retry_after = error['details']['retry_after']
    print(f"Rate limited. Retry after {retry_after} seconds")
else:
    print(f"Error {response.status_code}: {response.text}")

JavaScript

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

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

    if (response.status === 422) {
      console.error(`Validation error: ${error.message}`);
    } else if (response.status === 429) {
      console.error(`Rate limited. Retry after ${error.details.retry_after}s`);
    } else {
      console.error(`Error: ${error.message}`);
    }
    return;
  }

  const result = await response.json();
} catch (err) {
  console.error('Network error:', err);
}

Getting Help

If you encounter persistent errors:

1. Check the API status page
2. Review this documentation
3. Contact support: [email protected]

Include in your support request:

• Error code and message
• Request body (redact sensitive data)
• Timestamp
• Your API key prefix (first 8 characters only)