Chronologue uses FastAPI to serve a structured, schema-validated API for memory, planning, and scheduling operations. Clear error handling and standardized debug protocols are essential to supporting agents, developers, and users interacting with the system. This page documents all core error codes, response formats, debugging tools, and recommended resolution strategies for API clients and developers.

​
HTTP Status Code Reference

CodeMeaningDescription
200OKSuccessful request (default response)
201CreatedResource was successfully created
400Bad RequestRequest failed schema or logic validation
401UnauthorizedMissing or invalid API key
403ForbiddenValid auth but insufficient permissions
404Not FoundResource not found (trace, plan, event)
409ConflictResource already exists or cannot be merged
422Unprocessable EntityFailed Pydantic model validation
429Too Many RequestsExceeded rate limits
500Internal Server ErrorUnhandled backend error or crash

​
FastAPI Exception Handling

Chronologue uses FastAPI’s HTTPException to raise structured errors with code and message pairs. Pydantic model validation automatically returns 422 errors on bad inputs. Custom exceptions include:
  • TraceConflictException – raised on conflicting trace uid or edit attempts
  • PlanError – raised when agent plans fail structural checks or exceed constraints
  • UnauthorizedAgentAccess – used when an agent is not permitted to access a user trace
All exceptions return structured JSON.

​
Error Response Structure

All API errors return a JSON payload with the following shape: 
{
  "error": "Invalid tempo_token",
  "status": 400,
  "detail": "The provided tempo_token 'Morning@Night' is not recognized.",
  "trace_id": "req-abc123"
}
FieldDescription
errorBrief label describing the error
statusHTTP status code
detailExpanded explanation, with field or context references
trace_idRequest-level identifier for tracing/debugging
hint(Optional) Fix suggestions or reference documentation

​
Debugging Tools and Logging

Chronologue uses FastAPI’s logging module and Uvicorn’s structured output for diagnostics.

​
Developer Tips:

  • Each API response includes a trace_id header or field (if an error occurs)
  • Server logs use structured levels: TRACE, INFO, WARNING, ERROR
  • Logs can be routed to Sentry, Logtail, or other backends for inspection
To enable live logs locally: 
uvicorn chronologue.api.main:app --reload --log-level debug

​
Client-Side Debugging Tips

  • Use curl -v or Postman to inspect headers and body
  • Include Content-Type: application/json in all POST requests
  • Review full payloads: missing scheduled_for or malformed tempo_token can cause 422 errors
  • Validate request schema using examples in API reference

​
Common Error Patterns and Fixes

Error CodePatternResolution
422Pydantic validation failCheck required fields and types
409Duplicate uid or planUse PATCH or regenerate trace ID
403Agent not authorizedCheck agent scope or user ID binding
404Trace or event not foundVerify task_id or trace_uid
500Server errorRetry or contact support with trace_id

​
Trace Dump Endpoint (for Development Only)

POST /debug/trace-dump
  • Input: trace_uid, task_id, or linked_event_uid
  • Returns: full memory trace object, causal links, and profile metadata
  • Access: only enabled in debug mode (DEBUG=true)
Use this endpoint to inspect misbehaving traces or pre-runtime agent memory state.

​
Rate Limiting and Throttling

Chronologue applies soft rate limits by API key and IP address.
  • Default: 100 requests / minute / user
  • Status code: 429 Too Many Requests
  • Header: Retry-After: 30 (seconds)
Recommended strategy:
  • Use exponential backoff for retrying
  • Limit aggressive polling or synchronous agent executions

​
1Related Pages

Chronologue’s API is designed to fail transparently and traceably. Use structured error responses, trace IDs, and developer tools to quickly identify issues, debug behavior, and optimize your agent integrations.