Skip to main content

​
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

StatusMeaningCommon CausesFix
400 Bad RequestMalformed payloadMissing required field, invalid JSONCheck the request body against the API reference
401 UnauthorizedMissing or invalid credentialsNo Authorization header, expired JWT, wrong API keyRe-authenticate via the Gateway or refresh your token
403 ForbiddenValid auth, insufficient privilegeUsing a consumer JWT against an admin-only endpoint, tenant mismatchConfirm the key type matches the endpoint
404 Not FoundResource does not existWrong canonical path, moment not in ClockchainSearch first via /api/v1/moments?q=...
409 ConflictWrite collides with existing stateDuplicate moment, stale versionRe-fetch, then retry
422 Unprocessable EntityPayload validated but rejectedSchema mismatch, enum out of rangeCompare against the example in the relevant product page
429 Too Many RequestsRate limit exceededBurst traffic above your tierBack off using X-RateLimit-Reset (see below)
500 Internal Server ErrorUnhandled server errorTransient bug, upstream provider outageRetry with exponential backoff; if persistent, file an issue
502 / 503 / 504Gateway or upstream unavailableBackend deploy, model provider hiccupRetry; 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:
HeaderMeaning
X-RateLimit-LimitRequests allowed in the current window
X-RateLimit-RemainingRequests left in the window
X-RateLimit-ResetUnix epoch when the window resets
Current tiers (see Rate Limits for the canonical table):
TierLimitApplies To
Public60 / minClockchain unauthenticated reads
Auth reads300 / minAuthenticated GET
Auth writes30 / minAuthenticated 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:
CodeMeaningNext Step
auth.missingNo credentials presentedAdd Authorization: Bearer ... or X-API-Key: ...
auth.jwt_invalidJWT signature failedRe-auth via OAuth — the signing key may have rotated
auth.jwt_expiredJWT exp passedRefresh token via /api/v1/auth/refresh
auth.key_revokedAPI key deactivatedGenerate a new key in the dashboard
auth.insufficient_creditsAccount out of creditsTop 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, pro_simulate) require a JWT passed to the MCP client. See MCP Server → Tools.

​
Still Stuck?