Skip to main content

Documentation Index

Fetch the complete documentation index at: https://chronicle.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the most common issues developers may hit when working with the Chronicle API and MCP integrations. If you’re just getting started, first make sure you’ve:
  • created a valid API key
  • verified your request headers
  • tested a basic API call before trying generation or MCP flows

​
Authentication errors

HTTP status details for auth and other failures are summarized on Error codes.

​
401 Unauthorized

A 401 Unauthorized response usually means the API key is missing, invalid, malformed, or no longer active.

​
Checklist

  • Make sure you’re sending an API key with the request.
  • Use one of these supported formats:
    • Authorization: Bearer <api_key>
    • x-api-key: <api-key>
  • Confirm the key was created in the correct Chronicle workspace.
  • Check whether the key has been revoked or rotated.
  • Make sure there are no extra spaces, quotes, or truncated characters.

​
What to try next

  • Generate a new API key and retry the request.
  • Test with curl before debugging your app code.
  • Verify you’re calling the intended environment and base URL.

​
Rate limits and usage limits

If requests start failing intermittently, taking longer than expected, or returning rate-limit-related errors, your client may be sending too many requests too quickly. See API scope and rate limits for official rate-limit behavior, retry guidance, and polling recommendations.

​
What to do

  • Slow down request volume.
  • Avoid aggressive polling loops.
  • Add exponential backoff to retries.
  • Check usage-related fields in responses when available.
For long-running generation jobs:
  • wait 2-5 seconds between status checks
  • increase the delay gradually for longer jobs
  • stop polling after a reasonable timeout in your client

​
Retry strategy

Use exponential backoff with jitter for retriable failures. Example approach:
  • first retry after 2 seconds
  • second retry after 4 seconds
  • third retry after 8 seconds
Avoid immediate repeated retries, which can make the issue worse.

​
Generation job stays in progress

If POST /api/v1/presentations/generate starts successfully but appears to stay in progress for too long, the job may still be running, may be stuck, or may have failed downstream.

​
What to check

  • Make sure you’re polling the status endpoint rather than expecting a synchronous final result.
  • Inspect the returned status carefully.
  • If the job remains in a generating state for several minutes, treat it as failed in your client and surface the returned failure reason when available.
Your integration should:
  • create the generation job
  • poll status until completion or failure
  • handle timeouts gracefully
  • display useful progress or failure information to the user

​
Best practices

  • Do not assume the first poll will return a final result.
  • Build for async behavior from the start.
  • Surface progress information when available.
  • Capture and log error codes, messages, and request identifiers.

​
If the job seems stuck

Collect the following before contacting support:
  • request timestamp
  • workspace identifier
  • generation or artifact identifier
  • prompt used
  • template identifier, if one was provided

​
Generation completes but no usable presentation is returned

If generation completes but the response does not include a usable Chronicle presentation, the issue is often in the conversion from generated output into a real editable presentation.

​
Common symptoms

  • generation reports success, but no presentation URL is returned
  • output is incomplete or not usable by downstream clients
  • your client receives data that cannot be opened as a Chronicle presentation

​
What to try

  • Retry the request with a simpler prompt.
  • Retry with a known-good template.
  • Confirm your integration is reading the final completed payload, not an intermediate response.
  • Verify that your client is using the returned presentation URL or identifier when present.

​
How to handle this in docs and examples

Your implementation should assume that generation is a multi-step workflow:
  1. submit generation
  2. poll for completion
  3. read the completed presentation payload
  4. open or store the returned presentation URL or identifier

​
Template-created presentation appears blank or corrupted

If a presentation created from a template appears empty, incomplete, or corrupted, the failure may be related to how document state was stored or reconstructed.

​
What to check

  • Retry creation from the same template.
  • Try a different template to determine whether the issue is template-specific.
  • Confirm whether the issue reproduces consistently.
  • Test whether the issue is isolated to local or development environments.

​
What to capture

If you need help investigating, include:
  • template identifier
  • resulting presentation identifier
  • environment
  • timestamp of the request
  • whether the issue is reproducible across multiple templates

​
Client guidance

If your app receives a success response but the resulting presentation is unusable:
  • log the template id and created presentation id
  • show a recoverable error message to the user
  • allow the user to retry with a different template

​
MCP setup issues

If Claude Desktop or another MCP client does not detect Chronicle correctly, the problem is usually configuration, authentication, or connectivity.

​
Common symptoms

  • the MCP server does not appear in the client
  • no tools are discovered
  • authentication loops or never completes
  • tools appear, but every tool call fails

​
Checklist

  • Confirm the MCP configuration file is valid JSON.
  • Verify the configured command, path, or URL.
  • Restart the MCP client after making config changes.
  • Re-check environment variables, especially the API key.
  • Confirm the Chronicle API is reachable from the machine running the MCP client.

​
Local stdio integrations

For local MCP setups:
  • verify the server starts successfully from the command line
  • confirm the configured executable path is correct
  • make sure required environment variables are available to the MCP client process

​
Hosted MCP integrations

For hosted MCP setups:
  • verify the OAuth flow completed successfully
  • confirm the returned token is valid and scoped correctly
  • make sure your client can reach the MCP endpoint and authorization endpoints

​
MCP connects, but tool calls fail

If the MCP server is visible and tools are listed, but actual tool calls fail, the issue is often downstream authentication or network connectivity rather than MCP discovery itself.

​
Start with a minimal happy path

Test these in order:
  1. list templates
  2. create a presentation from a template
  3. fetch that presentation
If these succeed, the MCP transport is probably working and the issue is more likely isolated to generation or follow-up flows.

​
What to verify

  • the API key works in a direct REST API request
  • the Chronicle API is reachable from the host machine
  • there are no firewall, proxy, or network restrictions
  • your client handles upstream failures gracefully
If an MCP tool call fails:
  • retry once with backoff
  • log the error returned by the client
  • test the equivalent REST API call directly
  • reduce the workflow to the smallest reproducible example

​
Network errors and timeouts

Network failures can happen anywhere in the flow: during authentication, generation, polling, or MCP tool execution.

​
Best practices

  • set reasonable client-side timeouts
  • treat timeouts as retriable when safe
  • use idempotent retry behavior where possible
  • log full request context for failed calls
For any failed request, log:
  • endpoint
  • method
  • timestamp
  • response status
  • request id, if available
  • workspace id
  • relevant resource ids such as template id or presentation id

​
Before contacting support

If you’re still blocked, include as much of the following as possible:
  • the endpoint you called
  • the full HTTP status code
  • the response body
  • timestamp of the request
  • workspace identifier
  • API key creation time or whether the key was recently rotated
  • generation, template, or presentation identifiers involved
  • whether the issue is reproducible
This makes it much faster to diagnose auth issues, generation failures, template problems, and MCP setup issues.