Common errors - Ontologie Documentation

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 an Ontologie workspace.
An HTTP client (curl, Postman, Insomnia, or equivalent).

Authentication errors {#auth-errors}

401 Unauthorized {#401}

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 {#403}

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 /reference/api/queries/nodes
# - write:nodes for POST /reference/api/commands/execute

Request errors {#request-errors}

400 Bad Request {#400}

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 {#404}

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 {#409}

Symptoms:

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

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

Solution:

Reload the resource to get the latest version
Merge your changes
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 {#422}

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 {#429}

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 {#server-errors}

500 Internal Server Error {#500}

Actions:

Retry the request after 5 seconds
Check the status page
If persistent, report with the requestId

# Include the requestId in the support ticket
{
  "requestId": "req_abc123def456",
  "timestamp": "2024-01-15T10:30:00Z",
  "endpoint": "/reference/api/commands/execute",
  "payload": "..."
}

503 Service Unavailable {#503}

Possible causes:

Planned maintenance
System overload
Deployment in progress

Actions:

Check the status page
Retry with exponential backoff
Wait 5-10 minutes

Feature-specific errors {#feature-errors}

Modeler: Entity not visible {#modeler-entity-invisible}

Cause: Synchronization delay.

Solution: Wait 100ms then refresh the page.

Modeler: Relationship creation fails {#modeler-edge-fail}

Cause: Invalid source or target IDs.

Solution: Verify that both entities exist in the workspace.

Live Data: Source not connected {#livedata-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/connecter/donnees/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 {#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 {#api-keys-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 {#checklist}

Step 1: Check the connection {#step1}

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 {#step2}

# 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 {#step3}

# 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 {#step4}

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

Step 5: Enable verbose mode {#step5}

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 {#help}

Information to include {#info}

Request ID -- From the error response
Timestamp -- When the error occurred
Endpoint -- Full URL called
Request body -- Sanitized (no secrets)
Response -- Complete error message
Steps to reproduce

Support channels {#channels}

Email: support@growthsystemes.com
Status page: status.ontologie-growthsystemes.com

Need help?

Write to us: Support and contact.