Errors & Troubleshooting

Every Timepoint service is fronted by the API Gateway at api.timepointai.com (Clockchain public reads are also available directly at clockchain.timepointai.com). This page documents the error shapes, status codes, and rate-limit semantics you should expect — and a decision tree for the most common failures.

Error Response Shape

All Timepoint APIs return JSON. Non-2xx responses include a detail or error field describing what went wrong:

{
  "detail": "Invalid or expired token",
  "code": "auth.jwt_invalid"
}

Some endpoints return a bare {"detail": "..."} (FastAPI convention); others return a richer {"error": "...", "code": "..."} envelope. Always check response.status first, then parse the body.

HTTP Status Codes

Status	Meaning	Common Causes	Fix
`400 Bad Request`	Malformed payload	Missing required field, invalid JSON	Check the request body against the API reference
`401 Unauthorized`	Missing or invalid credentials	No `Authorization` header, expired JWT, wrong API key	Re-authenticate via the Gateway or refresh your token
`403 Forbidden`	Valid auth, insufficient privilege	Using a consumer JWT against an admin-only endpoint, tenant mismatch	Confirm the key type matches the endpoint
`404 Not Found`	Resource does not exist	Wrong canonical path, moment not in Clockchain	Search first via `/api/v1/moments?q=...`
`409 Conflict`	Write collides with existing state	Duplicate moment, stale version	Re-fetch, then retry
`422 Unprocessable Entity`	Payload validated but rejected	Schema mismatch, enum out of range	Compare against the example in the relevant product page
`429 Too Many Requests`	Rate limit exceeded	Burst traffic above your tier	Back off using `X-RateLimit-Reset` (see below)
`500 Internal Server Error`	Unhandled server error	Transient bug, upstream provider outage	Retry with exponential backoff; if persistent, file an issue
`502 / 503 / 504`	Gateway or upstream unavailable	Backend deploy, model provider hiccup	Retry; check status endpoints

Decision Tree

Use this to quickly localize a failure:

Got a 4xx or 5xx from api.timepointai.com?
│
├─ 401 Unauthorized ───────────► Is your JWT expired?          ──► Re-auth through OAuth
│                                Is the API key rotated?        ──► Regenerate in dashboard
│                                Wrong header name?             ──► Bearer → `Authorization`; API key → `X-API-Key`
│
├─ 403 Forbidden ──────────────► Endpoint needs admin/service?  ──► Switch to X-Admin-Key / X-Service-Key
│                                                                   (see /api-reference/authentication#auth-schemes)
│
├─ 404 Not Found ──────────────► Moment lookup?                 ──► Search first; canonical paths are slashy
│                                Wrong subdomain?               ──► Consumer calls go through api.timepointai.com
│
├─ 422 Unprocessable ──────────► Field type mismatch            ──► Compare to quickstart example (/quickstart)
│
├─ 429 Too Many Requests ─────► Respect `X-RateLimit-Reset`     ──► Sleep until that epoch, then retry
│
├─ 5xx from api.timepointai.com ► Retry 2x with backoff         ──► If persistent, check /api-reference/authentication#health-check
│
└─ Connection error ───────────► CORS preflight?                ──► Verify origin is *.timepointai.com
                                 DNS / TLS?                     ──► Check subdomain spelling

Rate Limits

The Gateway enforces per-tier limits. All rate-limited responses include these headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current window
`X-RateLimit-Remaining`	Requests left in the window
`X-RateLimit-Reset`	Unix epoch when the window resets

Current tiers (see Rate Limits for the canonical table):

Tier	Limit	Applies To
Public	60 / min	Clockchain unauthenticated reads
Auth reads	300 / min	Authenticated `GET`
Auth writes	30 / min	Authenticated `POST` / `PUT` / `DELETE`

Client guidance: on a 429, do not retry immediately — compute wait = X-RateLimit-Reset - now() and sleep. Burst retries cause further throttling.

Authentication Errors

Authentication failures come from the Gateway and follow this pattern:

{
  "detail": "Invalid or expired token",
  "code": "auth.jwt_invalid"
}

Common codes:

Code	Meaning	Next Step
`auth.missing`	No credentials presented	Add `Authorization: Bearer ...` or `X-API-Key: ...`
`auth.jwt_invalid`	JWT signature failed	Re-auth via OAuth — the signing key may have rotated
`auth.jwt_expired`	JWT `exp` passed	Refresh token via `/api/v1/auth/refresh`
`auth.key_revoked`	API key deactivated	Generate a new key in the dashboard
`auth.insufficient_credits`	Account out of credits	Top up via Billing

See Authentication → Auth Schemes for the full key-type matrix (Bearer JWT, API Key, X-Service-Key, X-Admin-Key).

MCP-Specific Errors

When using the Clockchain MCP server (clockchain.timepointai.com/mcp/), tool failures surface as MCP error objects rather than HTTP errors:

{
  "isError": true,
  "content": [{"type": "text", "text": "Tool 'flash_render' requires auth"}]
}

Unauthenticated tools (clockchain_stats, clockchain_search, clockchain_moment, clockchain_neighbors) work without credentials. Authenticated tools (flash_render) require a JWT passed to the MCP client. See MCP Server → Tools.

Still Stuck?

Check the health endpoints — a 5xx during a known outage is transient.
Compare your request against the Quickstart — copy-paste, then diff.
File an issue at github.com/timepointai.

Getting Started

Products

API Reference

Errors & Troubleshooting

Errors & Troubleshooting

Error Response Shape

HTTP Status Codes

Decision Tree

Rate Limits

Authentication Errors

MCP-Specific Errors

Still Stuck?

​Errors & Troubleshooting

​Error Response Shape

​HTTP Status Codes

​Decision Tree

​Rate Limits

​Authentication Errors

​MCP-Specific Errors

​Still Stuck?

Errors & Troubleshooting

Error Response Shape

HTTP Status Codes

Decision Tree

Rate Limits

Authentication Errors

MCP-Specific Errors

Still Stuck?