Error Handling

What breaks, why it breaks, and how to handle it across every SDK.

Common Errors

Status	Meaning	Typical Cause
400 Bad Request	Invalid input	Bad `event_kind`, payload over 256KB, too many link IDs (>100 total), invalid `context_id` format
401 Unauthorized	Auth failure	Missing or invalid `LOCUSGRAPH_AGENT_SECRET`
404 Not Found	Resource missing	Context doesn't exist (when calling `getContext`)
429 Rate Limited	Too many requests	Slow down or batch your calls

The most common mistake: forgetting to set LOCUSGRAPH_AGENT_SECRET. Every SDK call will return 401 until it is configured.

TypeScript:

try {
  await client.storeEvent({ ... });
} catch (error) {
  if (error instanceof Error) {
    console.error('Store failed:', error.message);
  }
}

Python:

try:
    client.store_event({...})
except RuntimeError as e:
    print(f"Store failed: {e}")

Rust:

match client.store_event(request) {
    Ok(response) => println!("Stored: {}", response.event_id),
    Err(e) => eprintln!("Store failed: {}", e),
}

Stay within these limits to avoid 400 errors:

Constraint	Limit
Event kind max length	128 characters
Context ID max length	256 characters
Link IDs per field (`reinforces`, `contradicts`, etc.)	50
Total link IDs across all fields	100
Payload max size	256KB
Batch events max	100 per call

If you hit 429 rate limits, switch to batch event storage. One batch call with 50 events is better than 50 individual calls.