Skip to main content

Common errors

At a glance​

This reference guide lists the most frequent Ontologie API errors, along with their causes and solutions.

Technical prerequisites​

  • An active API key with the required scopes.
  • Access to a Ontologie workspace.
  • An HTTP client (curl, Postman, Insomnia, or equivalent).

Authentication errors​

401 Unauthorized​

Symptoms:

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

Possible causes:

  • Missing Authorization header
  • Invalid API key format
  • Expired API key
  • Revoked API key

Solutions:

# Check the header format (must include "Bearer ")
curl -H "Authorization: Bearer df_xxx"  # Correct
curl -H "Authorization: df_xxx"         # Incorrect

# Verify that the key is valid in Settings > API Keys

403 Forbidden​

Symptoms:

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Insufficient permissions"
  }
}

Possible causes:

  • Missing required scope
  • Wrong workspace ID
  • Key not authorized for this workspace

Solutions:

# Check the workspace header
curl -H "x-workspace-id: $WORKSPACE_ID"

# Check the key scopes in Settings > API Keys
# Required scopes:
# - read:nodes for GET /api/queries/nodes
# - write:nodes for POST /api/commands/execute

Request errors​

400 Bad Request​

Symptoms:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { "field": "entityType", "issue": "required" }
  }
}

Solutions:

  • Check JSON syntax
  • Check required fields
  • Check field types (string vs number)
  • Validate UUID format
# Validate JSON before sending
echo '{"name":"test"}' | jq .

# Check UUID format
echo $ID | grep -E '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'

404 Not Found​

Possible causes:

  • Resource deleted
  • Wrong resource ID
  • Wrong endpoint URL
  • Resource in another workspace

Solutions:

# Check that the endpoint exists
curl "https://api.ontologie-growthsystemes.com/api/queries/nodes"  # Correct
curl "https://api.ontologie-growthsystemes.com/api/node"           # Incorrect

# Check that the resource exists
curl "https://api.ontologie-growthsystemes.com/api/queries/nodes/$ENTITY_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

409 Conflict​

Symptoms:

{
  "error": {
    "code": "CONFLICT",
    "message": "Version mismatch",
    "details": {
      "expectedVersion": 5,
      "actualVersion": 7
    }
  }
}

Cause: Version conflict -- another request modified the resource.

Solution:

  1. Reload the resource to get the latest version
  2. Merge your changes
  3. Retry with the new expectedVersion
# 1. Get the current version
VERSION=$(curl -s "https://api.ontologie-growthsystemes.com/api/queries/nodes/$ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" | jq '.data.version')

# 2. Update with the correct version
curl -X POST "https://api.ontologie-growthsystemes.com/api/commands/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"UPDATE_NODE\",
    \"payload\": { \"id\": \"$ID\", \"name\": \"New Name\" },
    \"expectedVersion\": $VERSION
  }"

422 Unprocessable Entity​

Symptoms:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "entityType": "must be one of: concept, object, process, actor"
    }
  }
}

Cause: Valid JSON but invalid data.

Solutions:

  • Check the allowed values for each field
  • Consult the endpoint documentation

429 Too Many Requests​

Symptoms:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Remaining: 0

Solutions:

// Implement exponential backoff
async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Maximum number of retries exceeded');
}

Server errors​

500 Internal Server Error​

Actions:

  1. Retry the request after 5 seconds
  2. Check the status page
  3. If persistent, report with the requestId
# Include the requestId in the support ticket
{
  "requestId": "req_abc123def456",
  "timestamp": "2024-01-15T10:30:00Z",
  "endpoint": "/api/commands/execute",
  "payload": "..."
}

503 Service Unavailable​

Possible causes:

  • Planned maintenance
  • System overload
  • Deployment in progress

Actions:

  1. Check the status page
  2. Retry with exponential backoff
  3. Wait 5-10 minutes

Feature-specific errors​

Modeler: Entity not visible​

Cause: Synchronization delay.

Solution: Wait 100ms then refresh the page.

Modeler: Relationship creation fails​

Cause: Invalid source or target IDs.

Solution: Verify that both entities exist in the workspace.

Live Data: Source not connected​

Possible causes:

  • Incorrect URL
  • Invalid credentials
  • Firewall blocking the connection

Solution: Use the connection test endpoint:

curl -X POST "https://api.ontologie-growthsystemes.com/api/live-data/test-connection" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "rest",
    "config": {
      "url": "https://api.example.com/data"
    }
  }'

RAG: Index not ready​

Symptoms:

{
  "error": {
    "code": "INDEX_NOT_READY",
    "message": "Vector index is still building"
  }
}

Solution: Wait for indexing to finish or trigger it manually:

# Check the status
curl "https://api.ontologie-growthsystemes.com/api/rag/index/status" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

API Keys: Insufficient scope​

Symptoms:

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "API key does not have required scope: write:nodes"
  }
}

Solution: Create a new key with the required scopes or edit the existing key.

Debugging checklist​

Step 1: Check the connection​

curl -s "https://api.ontologie-growthsystemes.com/api/queries/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

Step 2: Check authentication​

# Check the headers
curl -v "https://api.ontologie-growthsystemes.com/api/queries/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" 2>&1 | head -50

Step 3: Check the request format​

# Validate JSON
echo "$REQUEST_BODY" | jq .

# Test with a minimal payload
curl -X POST "https://api.ontologie-growthsystemes.com/api/commands/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"type":"CREATE_NODE","payload":{"name":"Test","entityType":"concept","position":{"x":0,"y":0}}}'

Step 4: Compare with the documentation​

  • Consult the API Reference for the correct endpoint
  • Check the required fields
  • Check the data types

Step 5: Enable verbose mode​

curl -v "https://api.ontologie-growthsystemes.com/api/queries/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-workspace-id: $WORKSPACE_ID"

Check:

  • Response headers
  • HTTP code
  • Response body

Getting help​

Information to include​

  1. Request ID -- From the error response
  2. Timestamp -- When the error occurred
  3. Endpoint -- Full URL called
  4. Request body -- Sanitized (no secrets)
  5. Response -- Complete error message
  6. Steps to reproduce

Support channels​

Need help?​

Write to us: Support and contact.